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Pre-f ace 


This manual is not intended -for the novice. It is not 
really suitable Tor someone who does not have a good grasp of 
the fundamentals of FORTH programming, at the very least to the 
extent that he understands the xForth introductory manual and 
all of its appendices very well. The main part of the manual 
IS the glossary, but the first part contains useful information 
such as memory maps. 

If you have difficulty with this manual, try reading one of 
the excellent books which are now becoming available, such as 
'Threaded Interpretive Languages' by Ronald Loeliger, published 
by Byte Books <a division of McGraw-Hill). 
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Chapter 1 

The inner interpreter 


Forth uses 
compact form. 
Forth words — 
of addresses. 


''indirect threaded code' to achieve its fast and 
Ail this means is that the definitions of raost 
those defined via the colon — contfsist of queues 
The addresses are so-cal1ed compiiation 


addresses isomertimes called code-field addresses) for which the 


corresponding memory 1ocation contains 
tifac:^ pointing to actual machine code. 


another address, 


thi - 




def 1 


address 


I def2 


> 1 


machine 
code 


JMP NEXT! 



This sounds unnecessarily complicated at first, and it has 
often been suggested that the middle link shown in the diagram 
should be removed, giving 'direct threaded code>', but the 
present consensus seems to be that the standard Forth o>.ettiod's 
gains in flexibility for advanced use outweigh the slight 
Iosses in speed and simp1icity. 

The diagram shows a colon definition (defl) being 
eK €!! cuted. At presen t we are at a point where def 2, wh i ch 
appearc^d in defies definition, is to be uscmJ. The compilation 
address cif def2 contains a pointer to machine code which is 
executed and which terminates in a jump to a system label NEXT. 
Control will then return to the 'inner intc^rpreter', v^hich 
arranges for the next compilation address in def1's queue to be 
usfi^d, and so on. (If def2 is a colon word too, the machine 
code executed will save defI's queue position on a special 
stack, then tell the inner interpreter to start looking up the 
con'ip^ ^ ^1'*i addresses in def2's queue. This is discussed in 
Chapter 2.) 


t y n 
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For the moment we are concerned only with how to run 
through a queue ot compilation addresses such as those in 
detl. The exact method difTers for different CPU's but the 
general idea is to keep the pointer which marks the place in 
def1's queue in a register, and to perform the indirection by a 
short routine starting at label NEXT. This routine has the* jab 
of looking up the contents of the address pointed to by thc^ 
register, ther^ looking up the address pointed to by what it has 
just looked up, and finally jumping to this last address^ All 
fn£\chine code segments have the duty to save the relevant 
register; in fact, the run—time code for colon actually saves 
it on the return stack (to be restored by semicolon) then puts 
a different value in the register so the inner interprete^r will 
start executing from a new queue. Other words such as BF^ANCH 
(the code compiled by ELSE) altf^r the register value without 
putting it on a stack, s^o giving the effect of a jump. 

In xForth, the inner interpreter lives in low memory, just 
after the table of initialization values. Its address is 
placed on the stack by the constant NEXT, so assembler words 
exit using JMP NEXT (or its equivalent in some other assembly 
language than Intel's 8080). The rest of this discussion refers 
to the xForth implementation in 8080 code, version 1.20 for 
CP/H2.2. Other versions and implementations for other languages 
and operating systems will differ in detail, but not in overall 
concept. 


The queue pointer referred to above is kept in the BC 
register, which must be saved and restored if necessary by any 
code you write- The value is pre-incrernented: that is, by the 
time there's some code being executed it points to the queue? 
position to be used next rather than the one currently being 
used. yhen the inner interpreter jumps to machine code, the DE 
register contains 1 more than the compilation address (of def2 
in the diagram). This value need not be preserved but is often 
U5seful to know. The return stack, used by colon and semicolon 
to push and pop BC register values, is an area in high memory 
at the top end of the terminal input buffer; the stacking 
mechanism is simulated, using a memory location as a stack 
pointer. 


Host of xForth is written at high level (i.e. as colcn 
definitions): bII of the disc handling and virtual memory, for 
example, uses high level words and communicates with CP/H 
the word CPH-CALL, which is a simple register-twiddle-and 
assembler word. The dictionary, which is a collection of 


definitions, grows up from low memory, starting just after' 


Vi a 
jump 
all 
the 


inner interpreter. The stack (sometimes called the parameter 
stack, to distinguish it from the return stack) uses the normal 
8080 stack pointer and grows down from high memory. Above the 
sitack base are the storage locations used by system variables 
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5uch as XCURSOR and BASE, and above them .are the disc 
input-output bu+fers, whose addresses are returned by the word 
BLOCK in virtual memory operations. The word SYSADAPT allows 
the number of blocks and the position of the top of the last 
block to be altered, by resetting various pointers and calling 
for a cold start. (Any words which try this should be written 
with great care, particularly if a cold start is not called, 
since the order of operations is significant; for example, 
stacks can end up overwriting one another if one is not 
careful.) All of this is summed up in the following memory 
map. 


Xfbcnt- i 

HevioCy M.A/. 


(&tart of Cjp^m) 


FKS.T. 







MBMORy MAP 
Courtesy of 

Forth Inbercst 
(3rroup 



ReruRfsi 

Stack n 


TERKlKCAi./ 

Buffer 



>»4 


" 


Tie. 





TfeXT BUFFCR 


PA> 


HERE 


WDR.1> BufFtR 




COL.)> START 7A8tE. 




loo H 















ii*^iitiiiiariiiiiiffiiiiiiif 


(c) A.I.H. Research The outer interpreter 

xForth technical manual 


Chapter 2 

The outer interpreter 



When xForth is first loaded, some initialization is done 
(see Chapter 7> and then QUIT is executed. QUIT is a 
colon-defined word whose* function is to pass control to the 
terminal: it does this by clearing the return stack (which may 
have had return addresses or data on it, if QUIT was executed 
from within some word) and then going into a loop. 

Clearing the return stack does not affect QUIT because the 
inner interpreter has its own pointer; if semicolon were to be 
executed there would be trouble, because semicolon tries to pop 
the return stack to find a return address, but QUIT’S loop is 
one from which there is no escape except via another QUIT. 

The important point about the loop is that it contains the 
word INTERPRET. Initially, INTERPRET is set by QUIT to read 
words from the terminal by setting variable BLK to zero. 
However, words such as LOAD reset the pointer BLK so that 
INTERPRET reads from elsewhere - in the case of LOAD, from 
virtual memory. At first INTERPRET merely calls on the inner 
interpreter to execute words successively from the input, until 
the input is exhausted. As explained in the introductory 
manual, some words such as colon switch INTERPRET over to 
storing the compilation addresses of words it meets, rather 
than executing them at once. This is done by changing the 
value of the variable STATE. If it is zero, words are executed 
as they are read while if it is nonzero, words are compiled 
unless they have been marked (by IMMEDIATE) for immediate 
execution. 

At this stage it is necessary to look a little more closely 
at the action of colon. When colon is executed by INTERF^RET, 
control passes to CREATE which reads the next word from the 
input and begins a dictionary entry for it, as described in 
Chapter 4. The dictionary entry has, in its compilation address 
field, a pointer to some special code which will adjust the 
return stack and the execution queue pointer when the new word 
is used later. The variable STATE is then set to a nonzero 
value (implementation-dependent) and control returns to the 
interpreter. From then on, until STATE is reset (by semicolon. 
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usually) non-immediate words are compiled: that is, their 
compilation addresses are entered into the queue in the 
dictionary entry for the new word- A typical immediate word is 
IF, which compiles a word OBRANCH. At execution time OBRANCH 
tests the stack top and, if it is zero, adjusts the queue 
pointer to point past the ELSE or ENDIF matching IF* 
(Obviously, the amount of adjustment is calculated at compile? 
time, when ENDIF is executed*) Semicolon is an immediate ward 
that resets STATE as already described, and compiles the word 
;S which pops the return stack into the queue pointer. 

The net effect of ail this is to give the familiar FORTH 
behaviours words are read from the terminal or virtual memory 
as required, and are executed or compiled as required. 

Sometimes it is necessary to alter the usual compiling 
process, though. This is done by the words CC0MPILE3 and L and 
J- If an IMMEDIATE word has to be compiled (such as a 
vocabulary name, if we want the vocabulary change to take place 
at execution time) it can be preceded by CC0MPILE3. The effe?ct 
of CC0MPILE3 (which is itself IMMEDIATE) is to force the word 
following it to compiled whether or not it is immediate. 
For example, 

: XXX ... tCOMPILE'j FORTH ... | 

More or less the opposite effect is obtained with C which 
is immediate and whose action is to set STATE to zero. STATE 
can be reset again by 3 so that 

s yyy ... C HEX 3 10 C DECIMAL 3 10 ... 5 

will compile code that when executed will put decimal 16 on the 
stack and then decimal 10 on the stack- (Had we not put in the 
word DECIMAL, ther e would be two i 6 s instead of a 16 and a 10, 
and at compile time the number base would still be set to 16 
after the semicolon.) The words C and 3 are useful for, say, 
calculating quantities known at compile time. They may be used 
in conjunction with I ITERAL which is an immediate word that 
compiles the vuiiue the? stack top as a literal to be put back 

on the stack at e. ion time. So 

: yyy ... C HEX 10 3 LITERAL 

C DECIMAL 10 3 LITERAL 

... 9 

achieves the same? effect as the previous definition of yyy- 

Non-trivial examples of these and other wonders are to be 
found in the system code on blocks 30 to 42 (in most systems). 


2-2 


(c) A-I.H, Research 
xForth technical manual 


tiic tionary headers 


Ch4^pter 3 
Dictionary header® 


A dictionary entry consists of two parts: a header and a 
body* The? header part consists of the name of the word and 
informatic3n linking the word to previous words to allow the 
dictionary to be searched* In versions of xForth up to i«2i5 
the header consists of a name field followed by a link field* 
In earlier versions (before 1*20) the name field is a character 
count and then a text string^ while in laiter versions the tErxt. 
string comes before the character count and is reversed; this 
is done to speed up dictionary searches* In all versions the 
link field is merely a pointer to the name field of the 
previous word in the dictionary- The character count is only 
valid in its low order 5 bits, since the remaining bits are 
used by SMUDGE and by IMMEDIATE* The precise details of all 
this may change in future systems. 

The body consists of a code field followed by a parameter 
field* The code field address is often also call€?d thc:} 
compilation address. The code field contains the threading 
pointer and in the case of a colon definition it points to the 
run™“time code -for colon. This code pushes the FlC register on 
the return stack and then sets BC to the first addr€?ss of the? 
parameter field, which will be the first member of the queue of 
words to be execiited L/ that colon word* For a variable, the 
code field points to some code that returns the address of the 
parameter field on the stack* For other words, the code field 
will point to whatever special code they correspond to* 

The word CREATE is used by ail words that make named 
diction£iry entries, CREATE reads the next word from the input 
stream and makes a dictionary header for it, then sc^ts the code 
field to point to the? code for VAfTIABLE, so that you can build 
tab1es by doing 

CREATE name 1 , 2 , 3 , 4 , 5 , 

which makes a dictionary entry called name, followed by a code 
field address which returns the address of a 10 byte region 
containing the? numbers 1 to 5, in order, (The word , (comma) 
takes the stack top and inserts it as a 2 byte value in the 
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dictionary, then increments the dictionary pointer.) Usually, 
CREATE is used in conjunction with a word DOES> that alters 
this tentative code field pointer to whatever is needed for the 
entry being created. 

The code field of a word can always be located using FIND 
and the parameter field can always be located using (tick). 
For example, FIND DROP will return the code field address of 
DROP (which contains a pointer to the very next 16 bit memory 
location, as it happens) while ’ DROP will return the parameter 
field address of DROP, which is 2 more than the code field 
address in versions up to 1.21. Is is passible to locate all of 
the fields in present versions of xForth, though for 
compatibility with FORTH—79 and with future versions of xForth 
this fact should not normally be used. The relevant words are 
CFA, LF'A, NFA and PFA, which are described in the glossary. 
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Chapter 4 
I CODE and DOES> 




De-fining words such as s or STRING have two jabs to do when 
they execute: they must create a dictionary entry and they must 
create a definition corresponding to that entry* The 
definition, as we have seen, is a code field a location 
containing the address of code to be executed - followed 
possibly by a parameter field, whose contents depend on the 
particular word* For example, the parameter field of a word 
defined by STRING is a pair of 16 bit locations containing the 
maximum length and the current length, followed by enough space 
to contain the maKimum length string- The code field points to 
code that returns the address of th€f text space and the current 
length- For a word defined by : on the other hand, the code 
field points to code that manipulates the return stack, while 
the p^irameter field is the queue of addresses mentioned in 
Cluipter 1, namely a sequc?nc:e of pointers to othcfr definition's'' 
code fields (compilation addresses), interspersed with in-line 
data such as numeric values of literals to be placed on the 
stack at execution time. 

We have already seen how CREATE makes a dictionary entry, 
but how are the code field and the parameter field of a new 
word produced? As we saw, CREATE does build the beginning of a 
definition after it makes the dictionary entry, since it makes 
the code field point to code that leaves the parameter field 
address on the stack. Often this will have to be changed, and 
nearly always a parameter field will have to be created. 

The easiest way to do this is to use the word DOES> after 
CREATE. Let us look at a simplified version of the word STRING. 
We want lO STRING s to create a dictionary entry called s with 
a parameter field containing 10, then the present length of s, 
then 10 bytes- When s executes we want it to leave the address 
of the start of those 10 bytes followed by the present length 
of s, so the code field of s will have to point to code that 
accomplishes this. Here is the definitian- 

: STRING CREATE ( Hake a dictionary header ) 

DUF^ y O , ( Put in max Zc present lengths ) 
ALLOT ( Leave enough space ) 
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DOEB> C Point to address at exec time 

2+ DUP 3 ( Present length on stack ) 

SWAP 2+ SWAP ; (Exit with addr & length ) 



When STRING executes, CREATE reads the next word trom the input 
stream (e.g. the word -following STRING) and makes a dictionary 
entry tor it. So 10 STRING s makes an entry called s. CREATE 
sets up a code tield like that ot VARIABLE but allots nothing 
to the parameter tield. Then DUP , stores the stack top (10 in 
the above example) in the parameter tield and allots space tor 
it so that the next assignment to the parameter tield vji 11 use 
another memory location- Next O , puts zero in the next memory 
location (so the string has initial length zero) and ALLOT 
takes the 10 that was DUPed to decide how much space to 
allocate to the text string. The dictionary pointer is lett 
pointing to the end of the? text space, ready tor another word 
to be created- 


Next, the special word D0ES> comes into action. Its job is 
to make the code tield point to the correct code, which is the 
code betvieen D0ES> and the semicolon in the detinition ot 
STRING. At execution time, the address ot the parameter will be 
pushed on the stack and the code tollowing D0ES> will be 
executed. Here, we add 2 to the start at the parameter tield 
to get the location containing the max length and then two 
again to get the address ot the text space. 


As another example, here is a simplitied version ot 
C3VARIABLE. 


s C3VARIABLE CREATE 

2$ ALLOT 
D0ES.> It 4- ; 

In this case, 10 C3VARIABLE vec makes a dictionary entry called 
vec and then allots 20 bytes (space tor 10 integers). 
Executing 3 vec mses the address ot vec's parameter tield, 
plus 6, to be It . i on the stack. In our simple exa/nple, no 
range checking is done either when vec is detined or when vec 
is executed, so -"lOO C 3 VARIABLE xx will cause disaster and 
0 20 vec ! may well do so. 


It is also possible to detine execution time code in 
assembly language, by replacing D0ES> with ;C0DE. In that case, 
everything between ;CODE and END-CODE will be assembled, and at 
execution time the interpreter will jump to just atter ;C0DE- 
To use this successtul1y, you have to know the details ot how 
your particular implementation simulates the Forth 
pseudo-machine, as in Chapter 1. For example, the 8080/Z80 
system has the BC register as the threading pointer tor the 
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inner interpreter, and the DE register contains 1 less than the 
parameter field address. The BC register must be restored 
before jumping to NEXT but the DE and HL registers need not 
be. Versions of xForth for different processors are supplied 
with the corresponding information about where the pointers are 
kept - 

Thus we could define CJVARIABLE' for the 8060/ZOO system by 


: CJVARIABLE 


CREATE 2% ALLOT 
; CODE 

D INX, 

H POP, 

H DAD, 

D DAD, 

NEXT 1- 

END-CODE 


< Hake space at ) 
( compile time. ) 
( And do this ) 
( at exec times > 
( D now points ) 

< to parm field.) 
( Get stack top.) 

< Double it. ) 

( Add the parm ) 

< field address > 
( to get addr ) 
( of required ) 
C element in HL. ) 

JHP, ( Push HL %< ) 

( return. ) 


where we have used the fact that location NEXT-1 contains 
H F^USH, Note that ; CODE does exactly what is theres there is no 
hidden pushing of the parameter field address onto the stack as 
in D0ES>, so we have to get it from the DE register. 
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Chapter S 

Virtual memory and th® -filing system. 


All virtual memory operations are done through the word 
BLOCK. Executing BLOCK results in the removal o-f a block number 
from the stack and its replacement by an address in true 
memory. 




BLOCK determines whether the required block is in memory 
and if so,, returns the buffer address at once. If the block is 
not in memory, BLOCK uses an approximation to a 'least recently 
used' algorithm for buffer allocation, to select a new buffer. 
Each buffer has a 16 bit tag whose high bit is set if UPDATE 
has been called. This method of marking blocks as updated may 
change in systems beyond 1.20. If the required buffer hits this 
bit set it is written to disc, the relevant: file being createtd 
if necessary. The final stage is to read the appropriate part 
of a disc file into the buffer and leave the buffer address on 
the stack. If the block has never before been written to, the 
first byte will be a CP/M end of file mark (control/!) and the 
next 127 bytes will be zero. The subsidiary words BUFFER and 
R/W are called by BLOCK to perform disc aperations- 

The connexion between disc files and block numbers, as 
de-?scribed in the Appendix of the users' manual, is established 
by the word GET—FILE, which maintains a table of files. The 
3rd file in the table corresponds to the 3rd virtual memory 
segment and so on; if no file is associated with a segment the 
stored address is O. Executing get—file causes a block number 
to be taken off the stack and divided by seg—size to give an 
index in the file table. If the corresponding table entry is 
zero an error message is given, and otherwise the file and the 
appropriate CP/fl record number are left on the stack. 

For example, if table entry 6 points to the xForth file 
structure file6 (so that 6 'th-FILE places the same thing in 
the stack as does file6) then 

6004 get-file 

leaves the same stack result as 


I zo 
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24 file6 

would, since the 4th Ik block of file6 starts with CP/M sector 
24 o-f the file. 

Sequential input-output is actually simulated using 
standard xForth virtual memory operations. This allows 
spooling to be done in virtual memory so that by allocating a 
large buffer space using SYSADAPT the user can minimire disc 
activity. Note that if the sequential input—output is needed, 
QUIT is redefined to type out the contents of the output spool, 
if any, and SAVE—BUFFERS is redefined to delete the input and 
output spools. 

Byte—oriented input—output via getc and putc is done by 
maintaining block and character pointers. If it is too slow 
the simplest solution is to write new words that do their own 
buffering and only call BLOCK occasionally rather than for 
every byte. (In particular, putiS could have been defined as a 
loop containing putc, but you can see how it does a block 
memory move instead.) 

The greatest advantage of using virtual memory for 
sequential input-output is in the simplicity of the pipe and 
redirection words, which (like COPY) just renumber virtual 
memory blocks using (copies). The word (copies) in (file-voc) 
is like COPIES except that COPIES flushes virtual memory then 
optimizes disc access, and always copies the requested number 
of blocks, while (copies) does not flush virtual memory, 
stealing blocks from its input even if they should have been 
written to disc. Also, (copies) stops at any block beginning 
with an end-of-file. Note that this means the input to 
(copies) may not be correctly represented on disc (which 
doesn’t matter for a spool file) and that, depending on the 
exact details of your CP/M implementation, it will usually stop 
at the first Ik block following the end of file. 
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Chapter 6 

ABORT, COLD and th® cold start tables 



When xForth is loaded and run, control is transferred to a 
short assembler segment that sets up the stack and return stack 
correctly, and then COLD is called. The job of COLD is to 
initialize such things as XEMIT, the variable containing the 
code executed by the word EMIT before the output painter OUT is 
incremented. All the information needed at initialization is 
contained in a table at the base of memory, which also contains 
information such as the version number. This table is read by 
COLD and written by PROTECT; the main part of the operation is 
a block memory transfer between the cold-start table (whose 
address is given by CS~TABLE) and the 'user variable' area, a 
region in high memory used for the current values of things 
like XEMIT. 

The last thing COLD does is call EMPTY-BUFFERS and then 
ABORT. ABORT resets the stack and return stack pointers 
(unnecessarily in this case, but often needed) and executes the 
code pointed to by XSIBNON. Then it calls QUIT which gives 
control to the terminal. 

Because of subtleties concerning the way multiple 
vocabularies are linked together, COLD is redefined by the 
xForth high level system to call EMPTY first if it is executed 
by the user or by a user-defined word. If this were not done, 
it would be possible to have mysterious delayed crashes caused 
by corruption of the dictionary structure in a way that only 
becomes evident later. 
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Append!K A 

Additional notes. 



The following are a few hints that may be helpful for users 
who want to change their systems. 

1. A minimal system can be constructed by altering black i 
of FORTH.BLK and the blocks and files that block 1 loads 
when SYSGEN is typed from the kernel system- You only' 
need the structuring words (except CASE and its friends) 
and the most elementary output words, plus a few assorted 
others, to have a FORTH-79 system- 

2- If you want to reserve an area in memory for use by other 
code (say, code from another compiler) and you are 
nervous about putting it directly into the dictionary, 
you can leave a gap between the top of xForth and the 
CP/M system- Do this by changing 6 5) in the word 

SYSADAPT to, say, 6 5) 1024 and then regenerating the 

system from the kernel. Then when you type, say, 

4 SYSADAPT the system will be set to observe the new 
upper limit and will put its buffers below this. 

3. The metacompiler can make words with no headers. This 
makes for a much smaller system- 

4. The two locations before the start of the inner 
interpreter contain D PUSH, and H PUSH, so to push both D 
and H from a CODE definition, end up by jumping to NEXT 
2- while to push just H jump to NEXT 1- 
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App«ndiK B 

Error handling. 



The F0RTH--79 Standard detines the following types of error 
condition- In xForth, the word ERROR is executed whenever an 
error is detected, and leads to the effect described below as 
long as the system variable WARNING has the value 1- For the 
effects of other values of WARNING, see the entry for WARNING. 

1. Input stream exhausted before a required <nanie>. The 
xForth system gives the error message 'Unexpected end of 
input'• 

2- Empty stack and full stack for the text interpreter. The 
xForth system gives the error message 'Empty stack' or 
'Full stack'. 

3. An unknown word which is not a valid number for the text 

interpreter. The xForth system gives an error message 

consisting of the unknown word, followed by a question 

mar k. 

4. Compilation of incorrectly nested conditionals. The 
xForth system gives the error message 'Conditionals 
incorrectly nested'. 

5. Interpretation of words restricted to compilation. If 

the word is IMMEDIATE, the xForth system gives the error 
message 'Compilation only; tried to use outside 

definition'. If the word is not IMMEDIATE, the error is 

icjnored and execution continues as usual. See the notes 
on the glossary for more details. 

6. FORGETting within the system to a point that removes a 
word required for correct execution. The xF'orth system 
gives the error message 'in protected dictionary'- 

7. Insufficient space remaining in the dictionary- The 

xForth system gives the error message 'Dictionary fuii'- 
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App«ndiK C 

Notes on the gloBsary. 


xForth is a FORTH-79 Standard System with Assembler 
Standard Extensions (if the assembler has been purchased). It 
contains nearly all of the words in the Double Number Standard 
Extension. 

The glossary that follows describes the action of nearly 

all xForth words in the vocabulary FORTH. Words in other 

vocabularies are not described, as they are typically 
specialised words not intended for use outside that vocabulary, 
e.g. (file voc) and (EDITOR). In general, words enc1osed in 
parentheses are specialised and not intended for normal use; if 
the parenthesised word is a vocabulary name none of the words 
in the vocabulary are intended for normal use. 

The glossary entries consist of a header with the word and 
its effect on the stack, followed in some cases by some 

information in square brackets. The stack effect is described 

in the form 

( stack-before - stack-after ) 

or, if the word reads from the input stream when it executes 
(e.g. VARIABLE), in the form 

( stack—before +++ stack—after ) 

stack—before and stack—after contains an ordered 
list of stack items, with the top of the stack (most 
accessible) on the right. The stack items are any of the 
following: 

n a signed 16 bit integer; 

u an unsigned 16 bit integer; 

«cldr a 16 bit address; 

bit stack item with only the low order 8 
bits of interest; 


C-l 
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char 


u 

■file 


d 


•flag 


a 16 bit stack item with only the low order 7 
bits of interest; 

a string identifier consisting of an address 
and a count of the number of characters; 

the address of the base of a file control 
structure; 

a 32 bit signed integer; 
a 32 bit unsigned integer; 

a boolean flags TRUE is defined as 1, FALSE as 
zero. All xForth supplied words treat anything 
nonzero as TRUE. 


The stack items are sometimes followed by digits 1, 2 etc where 
necessary to avoid ambiguity. 


The information in sguare brackets is one or more of the 
followings 


A number corresponding to the number of the F0RTH--79 
definition. 


The letter C, meaning that the word should only be used 
during compilation (i.e. within a colon definition. All 
such words that are also immediate execute ERROR if called 
outside a colon definition. Words such as >R do not give 
an error message in such cases, unless the DEBUG 
vocabulary is being used- The general action for words 
that give no error message is to continue execution, 
ignoring the error. However, the side effects of the 
incorrect use may be such as to crash the system. For 
this reason, we recommend that you use the DFBUG 
vocabulary for all testing. 

The letter I, meaning that the word is marked for 
immediate execution and so will execute even if 
encountered during a colon definition (e.g. IF). To 
compile an immediate word, precede it by CCOMPILEl. See 
the entries for CCOMPILEl and IMMEDIATE. 

The letter U, meaning the word is the name of a user 

variable <a system variable). See the glossary entry for 
USER. 


I 20 
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Glossary ai xForth words 


< n addr ~— ) 

Store n at address. "store” 


C1123 


!CSP (-) 

Save the stack position in variable CSP. Used tor 
error checks during compiling. 


< 0 ) j- j 

Interpreted or used in a colon detinition in the 
for mi 


Read the following text from the input stream, 
terminated by a double-quote. If executing, leave 
the address and length of a text string which will 
remain equal to the text read at least until the 
input stream is exhausted. If compiling, compile so 
that later execution will leave the address and 
length of such a text string, valid at all times- At 
least 127 characters are allowed in the text. If the 
input stream is exhausted before the terminating 
double-quote, ERROR is executed. "double-quote” 


< udl - ud2 ) Ci583 

Generate from an unsigned double number udl the 
next ASCII character, which is placed in an output 
£»tring. Result ud2 is the quotient after division fay 
BASE and is maintained for further processing. Used 
between <# and #>, "sharp” 


«->S { d - m > 

Convert double number d to a text string, 
according to the current base for output conversion. 
The string contains only digits, except that the 
first character is a minus sign if d is negative. If 
d is zero, the string consists of one zero. 
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otherwise, the leading digit is always nonzero. 


*> < d - «ddr n ) [j 

End pictured numeric output conversion. Drop d, 
leaving the text address, followed by the character 
count, suitable for TYPE, “sharp-greater” 


#BUFF <-n ) 

A constant returning the number of buffers at 
P^®sent allocated for virtual memory operations. 


#S ( ud-0 0) • 

Convert all digits of an unsigned 32 bit number 
ud, adding each to the pictured numeric output text, 
until remainder is zero. A single zero is added to 
the output string if the number was originally zero. 
Use only between <# and #>. “sharp-s” 


#fil«* (-n ) 

A constant returning 8, the number of virtual 
memory segments normally accessible to the user. 


•! < •! b2 - ) 

Assign the string literal si to the string 
'^^•^i^ble s2, truncating si at the right if necessary! 


< •! *2-«ddr3 n ) 

Concatenate strings. The string s2 is joined to 
the right of the string si, the result being left at 
the PAD. The PAD address addr3 and the length of the 
combined string is left on the stack. 


Glossary—2 





(c) A.I.H. Research 


Glossary o-f xForth words 


♦-># < s-d -flag ) 

Attempt to convert string s to a signed double 
number, according to the present BASE. The string may 
optionally be preceded by a minus sign, but otherwise 
may contain only digits in the present base. I-f the 
conversion succeeds, d contains the result and the 
flag is set to TRUE. 


( a - ud flag ) 

Attempt to convert string s to an unsigned double 
number. The behaviour is identical with that of $-># 
<which calls except that no leading minus is 
allowed. 


*< ( Bl m2 —- flag ) 

Return TRUE it si is lexically prior to s2, using 
ASCII ordering. 


< si b 2 - flag ) 

Return TRUE if the strings are identical. 


♦FIND < s - addr ) 

Attempt to locate the string s in the vocabulary, 
according to the rules for FIND. Identical to FIND 
except that string s is used instead of a string read 
from the input being interpreted. 


( -»•++ addr ) £ j 
Used in the form ' <name> 

If executing, leave the parameter field address 
of the next word accepted from the input stream. If 
compiling, compile this address as a literal; later- 
execution will place this value on the stack. ERROR 
is executed if <name> is not found after a search of 
CONTEXT and FORTH vocabularies (and any vocabularies 
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contained in CONTEXT!. Within a colon—definition, 
' <name> is identical to C ' <nafnB> 1 LITERAL, “tick" 


'»-FCB < fflddrl - «ddr2 ) 

Given the address addrl of a file control 
structure, return the address addr2 of a part of 
memory used to communicate file control information 
with the operating system. 


*o-STATUS-BYTE < file - «ddr > 

Return the address of a byte in the control 
structure of file that is used for information on the 
present status of the file (e.g. whether it is open). 


'«-nAm« < addr —— ■ ) 

Given the address of a file control structure, 
return the address and length of a string containing 
the ASCII name of the corresponding CP/M file. 


'th-FILE ( n - addr ) 

Return the address of the file control structure 
owning the n'th virtual memory segment, if this 
segment has been allocated to a file. Otherwise 
return O. If n is negative or too large ERROR is 
executed. The meaning of 'too large' depends on the 
system. 


< < +++ ) Cl,1223 

Used in the form ( ccc) 


Read and ignore characters from the input stream, 
until the next right parenthesis. Being a FORTH—79 
word, the left parenthesis must be fallowed by one 
blank. It may be used freely while executing or 
compiling. ERROR is executed if the input stream 
ends before a right parenthesis has been found. 
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(EDITOR) <-- ) 

L i 

The name of the vocabulary of internal screen 
editor words. Execution makes (EDITOR) the CONTEXT 
vocabulary. 


(FLUSH) (-) 

Request the operating system to write all blocks 
to mass-storage that have been flagged as UPDATEd, 
but do not necessarily force them or their directory 
information to be written physically. (The operating 
system may keep them in its own buffers.) Not 
intended for normal use. 


(ID) ( «ddr —~ n ) 

Given a name field address eddr, leave a string s 
containing the name. 


(LINE) ( nl n2 - s ) 

Return a 64 character string containing the text 
from line nl of block n2. 


< f i 1 »*-voc) <- 


CI3 


The name of the vocabulary of 
internally by the -filing system and 
intended to be accessed by other words, 
file 


words used 
not normally 
Contains the 


<»kip--*unti 1) ( addrl char —— addr2 ) 

Increase addr1 by O or more until the byte 
address pointed to contains char or O. Used by 
skip~"until but may also be used independently* 
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(»kip~whil®) ( «ddri ch®r - «ddr2 > 

Increase addri by O or more until the byte 
address pointed to does not contain char or does 
contain O. Used by skip—while but may also be used 
independently. 


t 


i nl n2 - n3 ) C13B] 

Leave the arithmetic product of nl and n2. 
"times" 


•/ < nl n2 n3 - n4 ) 12203 

Hultiply nl by n2, divide the result by n3, and 
leave the quotient n4, rounded towards zero. The 
intermediate product is maintained as a 32 bit value 
for greater precision than the otherwise equivalent 
nl n2 n3 t / "times—divide" 


*/H0D < nl n2 n3-- n4 nS ) di 

Multiply nl by n2, divide the result by n3, and 
leave the remainder n4 and the quotient n5. The 
intermediate product is maintained as a 32 bit 
value. The remainder has the same sign as nl. 
"ti mes-di vi de-mod '* 


< nl n2 - n3 ) Ci213 

Leave the arithmetic sum of nl and n2. "plus" 


+ ! 


( n fflddr — ) C1S73 

Add n to the 16 bit signed value at the address, 
"plus-store" 


+- ( nl n2 - n3 ) 


I ZO 
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, Apply the sign o-f n2 to nl, which is le-ft as n3. 


+LOOP 


i n 


) 


CI,C,1413 


Add the signed increment n to the loop index and 
compare the total with the limit. Return execution 
to the corresponding DO unless the new index is equal 
to or greater than the limit (n>0), or unless the new 
index is less than the limit (nKO) . Upon exit ■from 
the loop, discard the loop control parameters, 
continuing exaction beyond +LOaP. Index and limit are 
signed integers in the range < -32768 _ 32767 >. 

(Comment: It is an unfortunate Standards 
Committee decision that the limit for n<0 is 
irregular. Further consideration of the 
characteristic is likely.) 


( p-) 


C1433 


Allot two bytes in the dictionary and store n 
there. "comma" 


( nl n2 — n3 ) C1343 

^•-ifcjtract n2 from nl and leave the difference n3. 
"minus" 


' ” * Cl,1313 

Continue interpretation with the next block. 

"next block" 


—TRAILING ( addr nl - addr n2 ) C1483 

Adjust the character count nl of a text string 
beginning at addr to exclude trailing blanks, i.e. 
the characters at addr+n2 to addr+nl-1 are blanks. 
ERROR is executed if nl is negative. "dash—trai1ing" 


C1933 
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Display n converted according to BASE in a 
free-field format with one trailing blank. If n<0 
display a negative sign. "dot" 


< +++ ) 


Cl,1333 


Interpreted or used in a colon definition in the 
forms 


ccc“ 

Read the following text from the input stream, 
terminated by a double—quote. If executing, transmit 
this text to the selected output device. If 
compiling, compile so that later execution will 
transmit the text to the output device selected at 
execution time. At least 127 characters are allowed 
in the text. If the input stream is exhausted before 
the ter minating double quote, ERROR is executed- 
“dot-quote" 


.BASE (-) 

Type the present base for numeric input/output, 
in decimal. 



.CPU <-> 


Type the name of the CPU the present xForth 
version was designed for. 



-n 


resent vo da 



ary. 


,R 


< nl n2-) 


t zo 
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Type a signed number in the current base, right 
aligned in a field of width n2. 


.SIZE <-) 

Type the number of CP/M 256 byte pages that need 
to be SAVEd to make an executable copy of xForth. 


.STACK <-) 


Type a copy of the stack on the currently 
selected output device, without disturbing the stack. 


.STORE (-) 


Type the number of bytes presently available for 
dictionary and stack expansion. 


.VERSION ( - ) 

Type the version number of xForth being used. 


< nl n2 - n3 ) £1783 

Divide nl by n2 and leave the quotient n3, 
rounded towards zero. Overflow or divide by zero may 
not be detected on some processors, for efficiency 
reasons. If it is not faulted, division by zero 
gives the result “1. "divide" 


/MOD ( nl n2 - n3 n4 ) £1983 

Divide nl by n2 and leave the remainder n3 and 
the quotient n4. n3 has the same sign as nl. 

"divide—mod" 


0< ( n - flag ) 


£1443 
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True if n is negative. 


"zero-less 


II 



( n flag ) C1803 

True if n is zero. "zero-equals" 


0> < n — flag ) 

True if n is positive. "zero-greater" 


C1183 


OBRANCH ( flag - ) 

The execution time procedure to branch 
conditionally. If flag is O the following in-line 
number is added to the interpretive pointer (in BC in 
8080/Z80 systems) to branch ahead or back. Compiled 
by IF, UNTIL and WHILE. 


1+ < n-n+l ) 

Increment the stack top. “one-plus" 


£1071 



1+! ( addr-) 

Add 1 to the 16 bit number at address, 
“one—plus—store" 


1— < n-n-1 ) 

Decrement the stack top. "one-minus" 


£1051 


1-! ( addr-) 

Subtract 1 from the 16 bit number at address, 
"one—minus-store" 
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2DR0P < d-) 

Discard the double number on top o-f the stack. 
2DUP < d d d ) 

Duplicate the double number on top o-f the stack. 

20VER ( dl d2 - dl d2 dl ) 

Copy the second top stack double number. 

26WAP ( dl d2 —- d2 dl ) 
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Exchange the top two stack double numbers. 


79-STANDARD ( - ) 

L 1 

Execute ensuring that a FORTH-79 Standard system 
is available. Notes On xForth systems with version 
numbers 1.lx, this merely sets the FORTH vocabulary, 
which is guaranteed to contain all the FORTH—79 
words. However, it is the user's responsibility to 
ensure that none of these words has been redefined. 
It may be that the standard expects redefinition to 
be faulted: this is under consideration. 


I ( +++ ) 


C 116 ] 


A defining word used in the forms 

s <name> ... | 


Select the CONTEXT vocabulary to be identical to 
CURRENT. Create a dictionary entry for <name> in 
CURRENT, and set compilation mode. Words thus 
defined are called "colon—definitions". The 
dictionary entry created is temporarily made 
invisible to FIND by setting a "smudge" bit. The 
compilation addresses of subsequent non-immediate 
words from the input stream are stared into the 
dictionary to be executed when <name> is executed 
later. Immediate words are executed as encountered. 


Words in the input stream are looked up in the 
dictionary according to the convention for FIND. This 
means that the CONTEXT vocabulary is searched first, 
followed by any vocabularies contained in the CONTEXT 
vocabulary, in the reverse order they were defined. 
Note that all vocabularies chain to FORTH eventually, 
so FORTH is always searched. The chaining is such 
that an entire vocabulary is always searched before 
another one is tried; this includes definitions made 
after the vocabularies were originally chained 
together. 


^ word is not found, conversion and 
compilation of a literal single or double number or 
(with the floating point option installed) a floating 
point number is attempted, with regard to the current 
BASE. That failing, ERROR is executed. 
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Note that colon is not immediate in FORTH-79, 
though it is made so in FIG-Forth and in the xForth 
DEBUG vocabulary in order to catch the common error 
o-f a missing semicolon. 

“colon" 


» < - > Cl,C,1961 

Terminate a colon definition and stop 
compilation. Make the latest word created visible to 
FIND by unsetting its smudge bit. If compiling from 
mass storage and the input stream is exhausted before 
encountering ; ERROR is executed. “semi-colon" 


I CODE <-) CI,C,2061 

Define the run-time action of a word created by a 
mixed high and low level defining word. Used in the 
f orm j 



I <name> ... CREATE ... jCODE ... END-CODE 
and later <name> <namex> 


Marks the termination of the defining part of the 
defining word <name>, sets the CONTEXT vocabulary to 
ASSEMBLER, and begins the def ination of the run time 
action for words such as <na(nex> that will later be 
defined by <name>- On eKecution of <namex> the 
assembler language sequence between ;CODE and 
END-CODE will be entered• "semicolon—code” 



< ( nl n2-- ‘flag > 


C1393 




True if nl is less than n2a 


less—than” 
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<# 


Ci693 

Initialise pictured numeric output. The words* 

<# ♦♦ #S HOLD SIGN #> 


can be used to specify the conversion of a 
precision number into an ASCII character 
stored in right—to-le-ft order. "less—sharp" 


double 

string 


<< < ) 


Read the next word in the input stream 
tile name, and make that file the spooled 
reading with getc. "redirect-in" 


as a CP/M 
input for 


<" ( nl n2 - flag ) 

True if nl is less than or equal to n2. 

<> < nl n2 - flag ) 

True if nl is not equal to n2. "not—equal" 


<CMOVE> < addrl addr2 u - ) 


Move u bytes from addrl to addr2, 
nonzero. Overlapping moves are handled 
"bidirectional-cmove" 


if u is 
correctly. 


< nl n2 --flag ) 

True if nl is equal to n2. "equals" 


C1733 


) 


Make the previous spooled output 
spooled input for getc. "pipe" 


for putc the new 
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> < nl n2-flag > 

True if nl is greater than n2. "greatei—than" 


>- ( nl n2-flag ) 

True if nl is greater than or equal to n2. 


>> ( 4 -«-+ ) 

Read the next word in the input stream as a CP/M 
file name, and copy to that file the spooled output 
written previously by putc. "redirect—out" 


>IN (-addr ) !:U,20n 

Leave the address of a variable that contains the 
present character offset within the input stream. 
(Range O ... 1023) "to-in" 


>LINE (-addr ) 

A variable that is incremented by CR. May be used 
for paging control etc. 


' "-' i:C,2003 

Transfer n to the return stack. Every >R must be 
balanced by a R> in the same control structure 
nesting level of a colon—definition. "to—r" 


( addr-) C1943 

Display the signed 16 bit number at the address. 

“q uestion-mar k" 
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7CSP (-) 


Execute ERROR if 
differs from that saved 


the present stack 
in variable CSP. 


position 


7DEPTH < n - ) 


Execute ERROR if t^e 
entries below n itself. 


stack 


has less than 


n 


7DUP 


( n-n ) or ( n —»■ n n ) 

Duplicate n if it is non- zero. •• 


C 1843 


query—dup” 


7ERR0R ( flag „ 


If 

false. 


flag is TRUE, 
remove it and 


execute n ERROR. if fj 
n and continue normally. 


i s 



7EXEC (-) 

Execute Error h „„t executing. 


7L0AD1N8 


Execute ERROR if not 


loading from virtual 


memory. 


7PAIRS ( nl n2 - > 


Execute ERROR 
checking syntax of 


i^ nl is not equal 

conditionals. 


to 


n2- 


Used in 
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7PAUSE (-) 

If the variable XOFF-CHAR contains -1, do 
nothing. Otherwise, execute 7TERMINAL and if no key 
has been struck, do nothing; if control/C has been 
struck, execute 6 ERROR; if the key has the ASCII 
code in XOFF-CHAR then pause until another key is 
struck and then continue unless the key is control/C 
(which aborts as before). Called by CR after every 
new line is output. 


7STACK <-) 

Execute ERROR if the stack is out of bounds. 


7TERMINAL < - fl«g ) 

Return TRUE if any key has been struck, leaving 
the actual key to be read if desired from LAST-KEY 


3 < addr-n ) [:i993 

Leave on the stack the number contained at the 
address. "fetch" 


ABORT <-1 CiOll 

Clear the data and return stacks, setting 
execution mode. Return control to the terminal and 
execute the code pointed to by XSIGNON- 


ABS 


< n - !nl ) C1O03 

Leave the absolute value of n. "absolute" 


ALLOT ( n-} C1543 

Add n bytes to the parameter +ield the most 

recently defined word. The bytes are not initialized 


GloB©ary~17 






Glossary of xForth words 


<c) A.I.Ii. Research 


or changed by ALLOT. 


AND 


< nl n2-n3 ) 


£1833 


Leave the bitwise logical "and’ of nl and n2. 


ASCI I ( ++-♦• char ) 

Read the next word from the input and leave the 
ASCII code of its first character. 


ASSEMBLER 


£1,1663 


The name of the vocabulary of assembler words. 
Execution makes ASSEMBLER the CONTEXT vocabulary. 


B/BUF < - 1024 ) 

^ ^^^ostant returning 1024, the number of bytes in 
a virtual memory buffer. 


BASE ( - addr ) 


CU,1153 


Leave the address of a 
corrent input—output numeric 
must lie in the range 2...70. 


variable containing the 
conversion base, which 


BEGIN ( — ) J.J 

Used in a colon definition in the formss 

BEGIN - flag UNTIL or 

BEGIN - flag WHILE ... REPEAT 

BEGIN marks the start of a word sequence for 
repetitive execution. A BEGIN-UNTIL loop will be 
repeated until t flag is true; a BEGIN-WHILE-REPEAT 
loop will be rept'uted until the flag is false. The 
words after UNTIL or REPEAT will be executed when 
either loop is finished. flag is always dropped 
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after being tested. 

The effect of BEGIN and the other loop words is 
achieved by the fact that they are immediate and so 
can calculate branches, and can compile appropriate 
code, while a colon definition is being formed. 


BELL (-) 

Send ASCII code 7 to the terminal. This normally 
sounds a noise-maker. 


BINARY <-) 

Set the base for numeric input/output to 2. 


BL <-32 > 

A constant returning the ASCII code of a blank. 


BLANKS ( addr n — ) 

Fill memory with n blanks starting at addr. If 
n<‘=0 do nothing. 


BLK <-addr ) CU, 1323 

Leave the address of a variable containing the 
number of the mass storage block being interpreted as 
the input stream. If the content is zero, the input 
stream is taken from the terminal. "b—1—k" 


BLOCK ( n-addr ) 1C 1913 

Leave the address of the first byte in block n. 

If the block is not already in memory, it is 
transferred from mass storage into whichever memory 
buffer has been least recently accessed. If the 
block occupying that buffer has been UPDATEd <i-e. 
marked as modified) it is rewritten onto mass storage 
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before block n is read into the buffer. n is an 
unsigned number. If correct mass storage read or 
write is not possible, ERROR is executed. Only data 
within the latest block referenced by BLOCK is valid 
by byte address, due to sharing of the block buffers. 


BRANCH (-) 

The execution time procedure to branch 
unconditionally. The following in-line number is 
added to the interpretive pointer (in BC in 8080/Z80 

systems) to branch ahead or back. Compiled bv ELSE 
and REPEAT. r - 


BUFFER ( n — *ddr ) 


C1303 


This is used by BLOCK but not normally by other 
words. Obtain the next block buffer, assigning it to 
block n. The block is NOT read from mass storage. 
If the previous contents of the buffer has been 
marked as UPDATEd it is written to mass storage. If 
correct writing to mass storage is not passible, 
ERROR is executed. The address left is the first 
byte within the buffer for data storage. n is an 
unsigned number. 


BYE (-) 

Call SAVE-BUFFERS and then return control to the 
operating system. 


C! 


< n addr - > C2193 

Store the least significant 8 hits of n at addr 
"c-store" 


C, < bytel - ) 

Allot a byte in the dictionary, storing bytel 
there* 


Bl OBsary-"20 
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C/L (-n ) 

A constant returning the number of characters in 
a line of output. (Set to 80 on delivery.) 


C» ( «ddr-byt® ) !!:iS63 

Leave on the stack the contents of the byte at 
addr (with higher bits zero, in a 16 bit field). 
“c-fetch" 


CAN-KEY (-addr ) CIJ3 

A system variable containing the ASCII code of a 
key used during input by EXPECT and QUERY to remove 
all characters so far typed. 


CASE ( n - n ) £1,03 

Used in a colon definition in the form 

CASE ... OF _ ENDOF 

_OF_ENDOF 


DEFAULT .... 

ENDCASE 

Execute the first part between the OF ... ENDOF for 
which the stack top on entry to CASE matches the 
stack top on entry to OF. Note that the stack top is 
dropped by OF if the OF ... ENDOF part is performed. 
If any OF ... ENDOF part is performed, control passes 
from ENDOF to beyond ENDCASE. If there is no match 
execute any code between the final ENDOF and DEFAULT 
or ENDCASE, then execute the DEFAULT part if there is 
one. Note that DEFAULT does not remove the stack 
top, and ENDCASE only removes the stack top if there 
was no DEFAULT. In all cases continue beyond ENDCASE. 


CFA ( ffiddrl - addr2 ) 

Convert the parameter field address addrl of a 
definition to its code field address addr2. Not 


Glossary—21 








Glossary of xForth words 


<c) A.I.M. Research 


guaranteed to be available in 
xForth. 


future versions of 



CLOSE < Addr - flag ) 


Attempt to close the 
structure is at addr, 
successful and a false flag 


file whose file control 
leaving a true flag if 
otherwise. 


CMOVE < Addri Addr 2 n - ) 


C1533 


Move n bytes beginning at addrl 
contents of addrl are moved first, 
addr1+1 and so on. If n<=0 nothing 
3 I so <CMOVE>. “c—move** 


to addr2- 
then those 
is moved. 


The 

of 

See 


CODE ( +++ ) 

A defining word used in the form: 
CODE <name> ... END-CODE 


C1113 



to create a dictionary entry for <name>, to be 
defined by a following sequence of assembly language 
words. ASSEMBLER becomes the context vocabulary. 


COLD 


< 


) 


Reset the system to the state it had when PROTECT 
was last called, or to the initial start-up state. 
This includes removing all new definitions, resetting 
the filing system without saving buffers or closing 
files, and resetting all system and execution 
variables. Finally call ABORT. 


COMPILE (-) 


CC,14&3 


When a 
bit value 
COMPILE is 


word containing COMPILE executes, the 16 
following the compilation address of 
copied (compiled) into the dictionary. 
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Thus COMPILE DUP will copy the compilation address of 
DUP and COMPILE CO, 1 will copy zero. 


CONFIG (-> 

Load block 2. This is usually sot up to conduct a 
question and answer session with the user to set the 
values o-f things like DEL-KEY. 


CONSTANT < n -•-++ ) Cl853 

A defining word used in the form: 

n CONSTANT <name> 

to create a dictionary entry for <name>, leaving n in 
its parameter field. When <name> is later executed, 
n will be left on the stack. 


CONTEXT < ~— addr ) CU,1513 

Leave the address of a variable specifying the 
vocabulary in which dictionary searches are to be 
made (e.g. by FIND and during compilation). 


CONVERT < dl addrl — d2 «ddr2 ) C1953 

Convert the text beginning at addrl-*^! to a double 
number, with regard to BASE, and add it to dl to give 
d2. addr2 is the address of the first 
non-convertible character. 


COPIES ( nl n2 n3 - ) 

Copy block nl to n2, nl-*-l to ri2+l etc until n3 
blocks have been copied. Overlapping shifts are done 
correctly. 


COPY { nl n2 - ) 
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Copy block nl to n2. 


COUNT < Addr - «ddr+l n.) C1S93 

Used to convert text -from packed to string torm: 
in packed form the number o-f characters is stored in 
the -first byte, so COUNT merely returns the contents 
n ot that byte and increments the address. Range oT 
n is O,...,255. 

^oS -CMJU 

i nl byt® —- n2 ) 

Hake a call to the CP/M system -for -function byte 
with nl in the DE register. The contents of the HL 
register on return are left as n2. In CP/Ml.4 the 
contents of BA rather than the contents of HL are 
left. 


( n bytal-byt«2 ) 

Execute CPM CALL and then mask off the high order 
byte of the result. 



' ' C1603 

Make the current output device take a new line. 
(Send ASCII return and line feed.) Then increment 
the variable >LINE and execute 7PAUSE. Any word that 
produces output thus automatically checks for 
control/S (or other pause character set in XOFF-CHAR) 
and for control/C. 


CREATE ( +++ ) 

A defining word used in the form: 


C2393 


CREATE <name> to create a dictionary entry for 
<name>, without allocating any parameter field 
memory. When <name> is subsequently executed, the 
address of the first byte of its parameter field is 
left on the stack unless DOES> has modified the 
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dictionary entry- 


CRS ( n-) 

Perform CR n times if n>0. Do nothing if n<=0. 


C8-TABLE ( - addr ) 

Return the address of the base of a table used to 
initialize system variables on initial start or after 
COLD is typed. 


CSP < - *ddr ) 

A variable used for temporarily storing the stack 
pointer position. Used for error checks during 
compiling. 



CTRL < +++ char ) 

Read the next word from the input and leave the 
low order 5 bits of the ASCII code of its first 
character. 


CURRENT < - addr ) 


CU,1373 


Leave the address of a variable specifying the 
vocabulary into which new word definitions are to be 
entered. 


CURSOR < nl n2 - ) 

Execute the code pointed to by XCURSOR. The code 
should move the terminal's cursor to row nl and 
column n2, relative to O O as the top left corner. 



D+ ( dl d2-- d3 ) 


C2413 


I 20 
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Add signed double numbers dl and d2 and leave the 
result as d3- "d-plus" 



D4— ( dl n-d2 ) 

Apply the sign of n tea the double number dl, 
leaving it as d2- 


D. < d-> 

Type a signed doubl 
•followed by a blank, 
negative- “d-dot" 


C1293 

number in the current base, 
Display the sign only i-f 


D.R < d n- } 

Type a signed double number in the current base, 
right aligned in a field of width n. Display the 
sign only if negative. "d-dot"-r" 


D< 


( dl d2 - flag ) C2443 

True if dl is less than d2. "d-less-than" 


DABS < dl “— d2 ) 

Leave as a positive double number d2 the absolute 
value of a double number dl. The result lies in the 
range O,..., 2147483647 . 


DEBUG (-) 

The vocabulary used for debugging and tracing. 


DECIHAL <-) 


Z1971 


Set the input-output numeric conversion to 10. 
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DEFAULT < n - n ) Cl 

At compile time, arrange for ENDCASE not to 
compile code to drop the stack top. At execution 
time, do nothing. 


DEFINITIONS ( - ) C15S3 

Set CURRENT to the CONTEXT vocabulary so that 
subsequent definitions will be created in the 
vocabulary previously selected as CONTEXT. 


DEL-KEY ( - addr ) CU3 

A system variable containing the ASCII code of a 
key used during input by EXPECT or QUERY to remove 
the last character typed. 



DEPTH (-n ) 


12303 


Leave the number of 16 bit values contained in 
the data stack, before n was added. 


DIR ( n-) 


Display the directory of the disc in CP/M drive 
n, where n*l gives drive A and so on- 


DLITERAL ( d - ) 

If compiling, compile the stack double value d as 
a 32 bit literal, to be left on the stack at later 
execution. 



DNEQATE < d-~d > 


12453 


Leave the twos complement of a double number. 


I zo 
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DO ( ni n2-) 

Used in a colon definition in the formi 
DO ... LOOP or DO . . . -i-LOOP 


1421 


Start a counting loop. The loop inden begins at n2 
and terminates according to a test on the present 
value of the index and the limit nl. See LOOP or 
+LOOP for details of termination. Note that the loop 
is always performed at least once, because the test 
is made at the end. The index I only returns a valid 
quantity between DO and LOOP or +LOOP. 


DO ... LOOP may be nested to a great depthz the 
precise value depends on the system but will usually 
be at least 20. 


D0ES> ( -— ) 


CI,C,1683 


Dsfine the run time action of a word created by a 
high-level defining word. Used in the form: 


i <name> ... CREATE ... D0ES> ... } 
jand later <name> <namex> 


Marks the termination of the defining part of the 
defining word <name> and begins the definition of the 
run time action for words that will later be defined 
by <name>. On execution of <nameK> the sequence of 
words between D0ES> and ; will be executed, with the 
address of <nameM>'s parameter field on the stack, 
"does" 


DP <-addr ) j-y 

A system variable, the dictionary pointer, which 
contains the address of the next free memory location 
above the dictionary. Do not alter directly: read by 
HERE and change by ALLOT. 


DPL 


< 


addr ) 
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^ that, contains the number o-f digits to 
the right of the decimal on double number input. It 
may also be used to hold output column location of a 
decimal point, in user generated formatting- The 
value on single number input is -1. 


DROP < n-) 

Discard the number on top of the stack. 


C233] 


DUP < n - n n ) 

Duplicate the number on top of the stack. 


C2053 


ELSE <-) 


Used in a colon definition in the form; 


IF ... ELSE ... ENDIF or 
IF . . . ELSE . . . THEN 


CI,C,1673 


(The THEN form is the FORTH-79 standard.) ELSE 
executes after the true part following IF and passes 
execution to just beyond ENDIF or THEN. It also acts 
as a marker for the part to be executed if there is a 
false flag on the stack when IF executes. ELSE has 
no effect on the stack. See IF. 


EMIT < char - ) 


C2073 


Transmit char to the currently selected output 
device and increment OUT. 


EMITP ( char - ) 

Transmit char to the CP/M list device (the 
printer'). Do not increment OUT or look to see what 
devices are selected. 


EMITT ( char - ) 
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“terminal' Do CP/M console device (the 

terminal . Do not increment OUT or look to see what 
devices are selected. ^ 


EMPTY 


Remove all unprotected definitions 
altering the stacks. See PROTECT. 


without 


EMPTY-BUFFERS ( - > 

Mark all blocks as empty, whether 
were actually marked as updated. 


C1453 


they 


END-CODE 


^ code definition, resetting the 
CONFEXT vocabulary to the CURRENT vocabulary. If no 

errors have occurred, the code definition is made 
Bvailaible “for 


ENDCASE ( 


) or ( n-) 


At compile time, complete the 
statement as follows. Fill in 
addresses from instances of ENDOF 
has not been executed, compile 




action of a CASE 
all the branch 
Then if DEFAULT 
DROP so that at 


execution time, the stack top will be dropped if the 

point where ENDCASE was is reached rather than beinq 
jumped past from an ENDDF. ocing 


ENDIF <-) 


CI,C3 


A synonym for THEN 


ENDOF (-) 


CI,C3 


Pass control t-o beyond the next ENDCASE. 
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ENSURE-LIME ( n - ) 

If there are less than n character positions 
remaining on the present output line, execute CR „ 


EOF (-n > 

A constant returning the value (26) of the CP/M 
end—of—file marker. 


ERASE < addr n - ) 

Fill memory with n zeroes starting at addr. If 
n<'=0 do nothing. 


ERROR ( n-J 

Execute the code pointed to by XERROR. By 
default, the code is STD—ERROR which issues error 
message n and executes QUIT- 


EXECUTE < addr-) 


i:i633 


Execute the dictionary entry whose compilation 
address is on the stack. 


EXIT <-) 


EC,1173 


When compiled within 
terminate execution of that 
point. May not be used within 
anything has been left on the 


a colon-definition, 
definition, at that 
DO ... LOOP or i f 
return stack. 


EXPECT ( addr n —) Cl093 

Transfer characters from the terminal beginning 
at addr, upward, until a "return" has been received 
tbe count of n has been reached. Take no action 
for n<=0. One or two nulls are added at the end of 
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the text. 


EXPECT* < «ddr nl - «ddr n2 ) 

Execute EXPECT and return the address of the 
string read from the terminal, with its actual length 
n2. (Note n2<=nl.) 


FALSE ( —“ 0 ) 

A constant returning the value of a FALSE flag, 
namely O. 


FCREATE ( addr - ) 

Given the address of a file control structure, 
attempt to create a new disc file with the name given 
in the structure. If unsuccessful, execute ERROR. 


FENCE ( - addr ) 


CU3 


A system variable containing 
which FORGET will refuse to work. 


an address below 
Set by PROTECT- 


FILE ( +++ ) 

A defining word used in the form: 

FILE <name> 

to create a file control structure. The initial 
operating system name of the corresponding file is 
set to be the same as the xForth name. Since names 
are checked for correct operating system syntax, 
ERROR is exectited if <name> (after conversion to 
upper case if cessary) is not a legal operating 
system name. Lxecution of <name> leaves the address 
of the file control structure on the stack. See also 
fname! and 's—FCB. 
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iesjat the till 
but/eerjs to di^c- 
rfovedi except t 
al/locatled to/SYSFI 
:s staodarcy value, 
de-f aul t \di 



e for CP/M systems. 


FILL < Addr n byte --) C2343 

Fill memory beginning at addr with a sequence of 
n copies of byte. If n<=0 take no action. 


FIND < addr ) C203.1 

Leave the compilation address of the next word, 
which is read from the input stream. If that word 
cannot be found in the dictionary after a search of 
the CONTEXT vocabulary and all vocabularies contained 
in it, leave O. Note that all vocabularies chain to 
FORTH eventually, so FORTH is always searched. 
Chaining is done in such a way that all entries in a 
vocabulary are searched before the next vocabulary is 
tried. 


FIRST ( - addr ) 

A constant returning the address of the first 
virtual memory buffer. 


FORBET ( +++ ) C1863 

Used in the forms 

FORGET <name> 

Set the CONTEXT vocabulary to CURRENT and attempt to 
find <name> according to the conventions for FIND. If 
<name> cannot be found, ERROR is executed. If <name> 
is found, check whether it is protected and if so, 
cause an error; if not, remove <name> and all words 
added to the dictionary after <name>, regardless of 
their vocabulary. 
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FORTH ( — ) [1,1073 

The name of the primary vocabulary. EKecution 
makes FORTH the CONTEXT vocabulary. 

New definitions become a part of FORTH until a 
different CURRENT vocabulary is established. 

User vocabularies conclude by 'chaining’’ to 
FORTH, so it should be considered that FORTH is 
'contained' within each user's vocabulary. 


SET-FILE C nl - addr n2 ) 

For block nl, find the corresponding file if 
there is one, and return its address addr and the 
operating—system dependent sector number n2 of its 
base. If no file owns block nl, execute ERROR. 


here ( ~ addr ) C1B83 

Return the address of the next available 
dictionary location. 


HEX ( — ) 

Set the base for numeric input/output to 16. 


(-addr > 

A variable that stores the address of the latest 
character of text during numeric output conversion- 


HOLO < char —- > 


Ci7S3 


Insert char into a 
string. Hay only be used 


pictured numeric 
between <# and #>. 


output 




I 20 
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I (-n ) CC,i363 

Copy the loop index onto the data stack. May be 
only used in the form: 

DO . . . I . . . LOOP or DO . . . I . . . +LOaP 


ID. ( addr - ) 

Given a name field address addr, type the name. 



IF (flag-) CI*C,2i03 

Used in a colon-definition in the forms; 

flag IF . . . ELSE . . . THEN or 

flag IF . . . THEN 

If flag is true, the words following IF are executed 
and the words fallowing ELSE are skipped. The EISE 
part is optional. 

If flag is false, words between IF and ELSE, or 
between IF and THEN (when no ELSE is used), are 
skipped. IF-ELSE—THEN conditionals may be nested. 

In xForth, ENDIF is a synonym for THEN. 


IMMEDIATE (-) C1033 

Mark the most recently made dictionary entry as a 
word which will be executed when encountered during 
compilation rather than compiled. 


INDEX 


( n 1 T ^ 

Execute ^PAGE .then 
:h of blodks nA 


1 type/ the fir^ 


charTacter;^ 


each of blodks nA to n2, /executing JOR ajf ter/ea 
ch^racycers. stopped by hi^tt^ng coptr^/C 



INSTALL-t«* 


( +++ ) 
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Read the next word from the input stream as a 
CP/M file and make it the CP/M name of a tile control 
structure owning the segment of virtual memory beyond 
the last user—accessible segment. The file control 
structure has x Forth name in vocabulary 
(file—voc). It is used for temporary allocation by 
words such as LOAD-FILE. 


INTERPRET (-) 


Execute (or compile, if STATE is nonzero) the 
text from the present input. The input is from the 
keyboard if the value of BLK is nonzero and from the 
virtual memory block numbered by BLK otherwise. 


j ( - „ ) CC,2553 

Return the index of the next outer loop. May 
only be used within a nested DO-LOOP in the form: 

DO-DO-J_LOOP_LOOP 


KEY < —— char ) Ci003 

Leave the ASCII value of the next available 
character from the current input device. 


L/8 (-n ) 

A constant returning the number of lines in a VDU 
screen. (Set to 24 on delivery.) 


LABEL ( +4-+ ) 

A defining word used in the form 

LABEL <naflte> 

to set the CONTEXT and CURRENT vocabularies to 
ASSEMBLER and create a dictionary entry for <name>. 
Note that <name> will therefore be in the ASSEMBLER 
vocabulary. 
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LAST-KEY ( - char ) 

Return the ASCII code o-f the last key read by KEY 
or 7TERMINAL. 


LATEST < - «ddr ) 

Leave the name field address of the most recently 
created word in the CURRENT vocabulary. 


LEAVE < - > CC,2133 

Force termination of a DO-LOOP at the next LOOP 
or +LOOP by setting the loop limit equal to the 
current value of the index. The index itself remains 
unchanged, and execution proceeds normally until the 
loop terminating word is encountered. 


LFA ( addrl - addr2 ) 

Convert the parameter field address addrl of a 
definition to its link field address addr2. Not 
guaranteed to be available in future versions of 
xForth. 


LIMIT < —- addr ) 

A constant returning the address immediately 
beyond the last address used by xForth. By careful 
alteration of the value put into LIMIT by SYSADAPT 
the user can create areas of memory which can be 
reserved for other programs. 


LIST < n-) C1093 

List the ASCII symbolic contents of screen n on 
the current output device, setting SCR to contain n- 
n is unsigned. 
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LIST-FILE ( +++ ) 

Read the next word -from the input stream as a 
CP/M file name and list the file in LIST form if the 
file extension is .BLK Otherwise assume the file is 
an ASCII text file and list it as such. 



LITERAL < n-) [j 

If compiling, then compile the stack value n as a 
l/»-bit literal, which when later executed, will leave 
n on the stack. 


LOAD < n-) 


C2023 


Begin interpretation of screen n by making it the 
input stream; preserve the locators of the present 
input stream (from >IN and BLK). If interpretation is 
not terminated explicitly it wi11 be terminated when 
the input stream is exhausted. Control then returns 
to the input stream containing LOAD, determined by 
the input stream locators >IN and BLK. 


LOAD-FILE ( +++ ) 

Read the next word from the input stream as a 
CP/M file name and LOAD the first block of the file 
if the file extension is .BLK Otherwise ERROR is 
executed. 
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LOOP <-) CX,C,1243 

Increment the DO—LOOP index by one, terminating 
the loop it the new index is equal to or greater than 
the limit. The limit and index are signed numbers in 
the range -32, 76.8, . . . , 32, 767. 


H* ( nl n2 - d ) 

Multiply nl by n2, leaving the result as a 32 bit 
signed number d. 



M/ < d nl - n2 n3 ) 

A mixed magnitude operator that leaves the signed 
remainder n2 and signed quotient n3 -From a 32 bit 
signed dividend d and a 16 bit signed divisor nl. 
The remainder takes its sign from the dividend. 


M/MOD ( udl ul - u2 ud2 ) 

An unsigned mixed precision version of /MOD, 
leaving a double quotient ud2 and a single remainder 
u2 obtained by dividing the single number ul into the 
double number udl. 


MAS < nl n2 - n3 > C21B3 

Leave the greater of two numbers. “max" 


MESSAGE ( n - ) 

Typo error message n but continue normally. 



MIN ( nl n2-n3 ) 


C1273 


I 20 
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Leave f he lesser of two numbers. "min" 


MOD < nl n2 - n3 ) C1043 

Divide nl by n2, leaving the remainder n3, with 
the same sign as nl. "mod" 


MOVE < addrl «ddr2 n - > [1133 

Move the specified quantity n of 16-bit memory 
cells beginning at addrl into memory at addr2. The 
contents of addrl is moved first. If n is negative 
or zero, nothing is moved. 


MYSELF ( — ) 

Compile a reference to the latest definition 
(usually the definition MYSELF is contained in). 
Allows recursion- 


NE8ATE < n - ~n> C1773 

Leave the two's complement of a number, i.e., the 
difference of O less n. 


NEXT < - addr ) 

A constant returning the address of the xForth 
inner interpreter, which must be jumped to by 
assembler words if normal threading is to resume. 


NFA < addrl - addr2 ) 

Convert the parameter field address addrl of a 
definition to its name field address addr2. Not 
guaranteed to be available in future versions of 
xForth. 
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NOOP (-) 

Do nothing. 


NOT < flagt - fl«Q2 ) C1653 

Reverse the boolean value of flagl. This is 
identical to 0“=. 


NUMBER ( «ddr - d ) 

Convert a character string left at addr, with a 
count at addr—1, to a signed double number d 
according to the present value contained in BASE. If 
a decimal point is encountered in the text, its 
position will be given in DPL but no other effect 
occurs. If numeric conversion is impossible, ERROR 
will be executed. 



OF ( nl n2 —nl ) or < nl n2 --> CI,C3 

If nl is not equal to n2, pass control to beyond 
the next ENDOF, leaving nl on the stack for further 
testing. If nl’=n2, continue execution beyond OF 
having removed nl and n2 from the stack. 


OPEN < addr — flag ) 

Attempt to open the file whose file control 
structure is at addr, leaving a true flag if 
successful and a false flag otherwise- 


OR 


( nl n2 - n3 ) E2233 

Leave the bitwise inclusive-or of two numbers. 



OUT ( --— addr ) 

A variable holding the present position of the 
output pointer. Incremented by EMIT, reset to O by 


t zo 
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OVER 


P! 


P9 


PAD 


PAGE 


PFA 


PICK 


CR and adjusted by all other xForth output words. 


< nl n2 - nl n2 nl ) ClTOl 

Leave a copy of the second number on the stack. 


( bytel byt«2 - ) 

Send bytel to the 8080 port address given by 
byte2. “p-store" 


< bytel - byta2 ) 

Return the byte obtained by inputting -from the 
8080 port address given by bytel. “p—fetch” 


C -— «ddr ) S:2263 

The address o-f a scratch area used to hold 
character strings for intermediate processing. The 
minimum capacity of PAD is 64 characters (addr 
through addr+63>. 


( - ) 

Execute the definition pointed to by XPAGE. 
Usually causes a paper throw or blanks a screen. 


< addrl - addr2 ) 

Convert the name field address addrl of a 
definition to its parameter field address addr2. Not 
guaranteed to be available in future versions of 
xForth. 


< nl-n2 ) 


C2403 
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Return the contents of the nl-th stack value, not 
counting nl itself. ERROR is executed if n is less 
than one. 

2 PICK is equivalent to OVER. 


PREV ( - addr ) CU 

A system variable containing the number of the 
block most recently referenced via BLOCK. The high 
bit of the block number is set if the block is 
updated. 


V™ 


Addr 


Pj^INTEp-pN? 

1 / 1a varLabli that 

, /copied to thi prin 
' ^ EXPt^T^^p^r may t^e 



s^t tcy : 
Wog^ed 
and r^det ui 



PROTECT <-> 

Set the initialisation sequence so that the 
present state will be restored by COLD. Set the 
variable FENCE so that all definitions presently 
existing are protected against removal by FORGET or 
EMPTY. 


QUERY <-) C2: 

Accept input of up to 80 characters (or until a 
Veturn') from the operator’s terminal, into the 
terminal input buffer. WORD may be used to accept 
text from this buffer as the input stream, by setting 
>IN and BLK to zero. 


QUIT C-) C2111 

Clear the return stack, setting execution mode, 
and return control to the terminal. No message is 
given. 
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<-addr > j;y 

A system variable that is used by the editors 
(for example) to keep track of the cursor position. 


R/W < addr n flag - ) 

Read or write block n to a IK buffer starting at 
addr. If flag is 1 then read; if flag is O then 
This word does all file allocation and^ if 
necessary, creation or opening of disc files. 
Normally for system use only; not guaranteed to be 
present in future releases of xForth. 


R> 


' " ' CC,1103 

Transfer n from the return stack to the data 
stack. *‘r~from'* 


R9 


' " * CCs2203 

Copy the number on the top of the return stack to 
the data stack. "r-fetch" 


REPEAT (-) 

Used in a colon definition in the forms 
BEGIN ... WHILE ... REPEAT 


Cl,C,1203 


At run-time, REPEAT returns to just after the 
corresponding BEGIN. 


REPLACED—BY < addr ++■♦- ) 

Find the compile ion address of the next word in 
the input stream, anu store it in addr. If the next 
word has not previously been compiled, execute ERROR. 


Glossary 44 







(c) A.I.H. Research 


Glossary of xForth words 


RESTORE-««^ < - ) 

If used after INSTALL—and before control has 
been returned to the console, restores the name of 
the temporary file to what it was before 
INSTALL—was executed. 


REVERSE < a - ) 

Reverse the order of the characters of s. Note 
that this is done in place so s should always be a 
'safe' copy of an original. Used mainly by the 
system, but can be used with care by users. 


ROLL < n - ) C2363 

Extract the n'th stack value to the top of the 
stack, not counting n itself, moving the remaining 
values into the vacated position. ERROR is executed 
if n is less than one. 

3 ROLL = ROT 

1 ROLL * null operation 


ROT < nl n2 n3 - n2 n3 nl ) C2123 

Rotate the top three values, bringing the deepest 
to the top. "rote" 


RP! (-> 

Resets the return stack pointer. Note that this 
means execution of ;S las compiled by ;) may crash 
the system: RP! should not normally be called by the 
user. 


S->D ( n - d ) 

Extend the signed single number n to a signed 
double number d- 
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SAVE-BUFFERS (-) C2213 

Write all blocks to mass-storage that have been 
flagged as UPDATEd. ERROR is executed i-f mass-storage 
writif' • not completed. 



SEE-FILE < +++ > 

Read the next word from the input stream as a 
CP/M file name and invoke the screen editor with the 
cursor pointing to the first character of the file, 
if the file extension is .BLK 


SIGN < n-) i:C,1403 

Insert the ASCII (minus sign) into the 

pictured numeric output string, if n is negative. 


SMUDGE < — ) 

Used during word definition to toggle the "smudge 
bit' of the name field of the latest definition, 


I zo 
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i,e. the one whose name field address is contained 
in the variable LATEST. This prevents the word from 
being found by FIND and so makes an uncompleted 
definition invisible until it is completed without 
error. 


8P! < any-) 

Discard all items on the stack. “stack pointer- 
store" 


BPS < - addr ) 

A system dependent procedure to return the 
address of the stack top as it was before SP3 was 
executed- Not normally for user execution. 


SPACE <-) C2323 

Transmit an ASCII blank to the current output 
device. 


SPACES ( n - ) 


C2313 


Transmit n spaces to the current output device. 
Take no action if n<=0. 


STATE < - addr ) CU,1643 

Leave the address of the variable containing the 
compilation state. A non-zero content indicates 
compilation is occurring, but the value itself may 
depend on the version of xForth. 


STD-ERROR < n-) 

The default code executed by ERROR. Executes 
n MESSAGE and then QUIT. 
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STRING ( n ++* ) 

A defining word used in the -form: 

n STRING <narae> 

to create a dictionary entry which is a string 
variable to hold a text string of length up to n 
characters. If n exceeds 255, the maximum length 
will be 255. At execution time, <name> returns the 
address of the first character and the current length 
of the string in a form suitable for TYPE. 


SWAP < nl n2 --n2 nl > 

Exchange the top two stack numbers. 


1:230 3 


SYSADAPT < n - ) 

Call PROTECT then set the initialisation sequence 
so that n buffers will be used for virtual memory, 
and set LIMIT so that when COLD is executed, all 
possible memory will be used. Then call COLD. Note 
that the code of SYSADAPT may be changed to set LIMIT 
to some different value so that not all possible 
memory will be used. 


SYSFILE { - «ddr > 

Return the address of a file control structure 
owning virtual memory segment O. (Blocks 1 to 1000 in 
the standard system). 


SYSGEN ( --) 

Generate the standard system from the kernel 
system. If the present system is not the kernel 
system, execute ERROR. 


TAB < n-) 


I so 
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as many spaces as needed to bring the output 
to position n, if possible. Otherwise do 


> Cl,C,1613 

in a colon-definition, in the form: 

IF ... ELSE ... THEN or 
IF-THEN 

THEN is the point where the execution resumes after 
ELSE or IF (when no ELSE is present). 


TIB <-addr ) |[U3 

A system variable containing the address of the 
terminal input buffer. 


Type 
pointer 
nothing. 


THEN ( - 

Used 



TOGGLE < addr bytel - ) 

Complement the byte at addr by the bit pattern 
contained in bytel. 



TRUE <-1 ) 

A constant returning the value of a TRUE flag, 
namely 1. 



TYPE ( addr n - ) C2223 

Transmit n characters beginning at address to the 
current output device. No action takes place for n 
less than or equal to zero. 


I zo 
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U# ( B-B ) 

Apply UCHAR to each character of s, so changing 
it to upper case if it was a letter and stripping the 
high bit in all cases. Note that the operation is 
done in place, i.e. the actual s is changed. 


U* < uni un2 - ud3 ) C2423 

Perform an unsigned multiplication of uni by un2, 
leaving the double number product ud3. All values 
are unsigned. "u-times*' 


( un-) C106:i 

Display un converted according to BASE as an 
unsigned number, in a free-field format, with one 
trailing blank. *‘u—dot” 


U. R < u n-) 

Print the unsigned 16 bit value u right aligned 
in a field of width n. If n is too small, overflow 
to the right as required. 


U/HOD <udl un2 - un3 un4 ) C2433 

Perform the unsigned division of double number 
udl by un2, leaving the remainder un3, and quotient 
un4. All values are unsigned. ”u—divide—mod” 


U< C uni un2 - flag ) C1503 

Leave the flag representing the magnitude 
comparison of uni < un2 where uni and un2 are treated 
as 16-bit unsigned integers. ”u-less-than" 


UCHAR < byte - char ) 
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Remove the high bit of byte; if the corresponding 
character is lower case, convert it to upper case* 


UNTIL (flag — ) 


CIj,C,237.1 


yithin a colon definition, mark the end of a 
BEGIN"-liNTIL loop, which will terminate based on a 
flag* If flag is true, the loop is terminated. If 
flag is false, execution returns to the first word 
after BEGIN* BEGIN—UNTIL structures may be nested- 


UPDATE ( — ) 1:2293 

Hark the most recently referenced block as 
modified* The block will subsequently be 
automatically transferred to mass storage should its 
memory buffer be needed for storage of a different 
block, or upon execution of SAVE-BUFFERS* 


USER ( n } 

A defining word used in the forms 

n USER <name> 

to create a dictionary entry for a system (or "user^) 
variable. The value of n is the offset relative to 
the user register pointer* When <name> is executed, 
the address left will be the sum of n and the user 
register pointer* Used to put variables in RAM when 
the system itself is in ROM, and in multi-user 
systems- 


VARIABI.E ( ) 1:2273 

A defining word used in the forms 

VARIABLE <name> 

to create a dictionary entry for <name> and allot two 
bytes for storage in the parameter field* The 
application must initialize the storecJ value, i.e* 
xForth does not set it to any particular value* Uhen 
<name> is later executed, it will place the storage 
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address on the stack. 


VLIST (-) 

List all the words in the present context 
vocabulary, and all vocabularies contained in it. 
May be stopped by hitting control/C. 


VOC-LINK < —~ «ddr ) CU3 

A system variable used for vocabulary linking. 
Not for user alteration! 


VOCABULARY < +++ ) C20B3 

A defining word used in the forms 


VOCABULARY <name> 


to create <in the CURRENT vocabulary) a 
dictionary entry for <name>, specifying a new ordered 
list of wt. J definitions. Subsequent execution of 
<name> will make it the COf• TEXT vocabul y. When 
<name> becomes the CURRENT vocabulary (see 
DEFINITIONS), new definitions will be created in that 
list. 

In xForth, new vocabularies chain to the 
vocabulary they were created in, so that when a 
dictionary search through a vocabulary is exhausted, 
the vocabulary they chain to is searched. The search 
starts with the most recently created word, whether 
or not that word was created after the outer 
vocabulary. 


WARM ( --) 

Call EMPTY-BUFFERS and then ABORT. 


WARNING (-addr ) CU3 
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A system variable used tor error handling. It 
its loM order bit is set to 1^ error messages are 
read trom blocks 4 onwards ot FILE-A. It the low 
order bit is set to O, numeric error messages are 
given. It the high order (sign) bit is set to zero, 
a warning message (message 4) is given when a word is 
redetined. It the high order bit is set to 1, 
message 4 is suppressed. 


WHERE ( nl n2 — > 

Invoke the screen editor with the cursor pointing 
atter character nl ot block n2. It used after ERROR 
caused by a compilation error while reading from 
disc, will leave the cursor just atter the word where 
the error was detected. 


WHILE (flag - ) Cl,0,149] 

Used in a colon definition in the forms 
BEGIN ... WHILE ... REPEAT 

Select conditional execution based on the flag. On a 
true flag, continue execution through to REPEAT, 
which then returns back to just after BEGIN. On a 
false flag, transfer execution to just atter REPEAT. 


WIDTH ( —— addr ) j;U 

A system variable containing the maximum number 
ot letters saved in the compilation ot a definition's 
name. The default value is 31 and the allowed range 
is 1,...,31. If the value of WIDTH is less than the 
natural character count for a word, only WIDTH 
characters will be saved, together with the actual 
character count- 


WORD ( char +++ addr ) [i 

Receive characters trom the input stream until 
the non-zero delimiting character is encountered or 
the input stream is exhausted, ignoring leading 
delimiters. The characters are stored as a packed 
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string at addr, with the character count at addr and 
the string following. The actual delimiter 
encountered (char or null) is stored at the end of 
the text but is not included in the count. 

Note: The facts that <i) leading delimiters are 
skipped, and (ii) WORD needs to move its text to 
insert the count, often lead to difficulties. The 
xForth words skip-while and wrap achieve the same 
effects as WORD with greater flexibility. 



XCURSOR < —™ addr ) 

A system variable 
address of the code used 


XEMIT ( - addr > 

A system variable 
address of the code used 


XERROR < ”— addr ) 

A system variable 
address of the code used 
initially. 


CU3 

containing the compilation 
by CURSOR. 


EUl 

containing the compilation 
by EMIT. 


CU3 

containing the compilation 
by ERROR. Set to STD-ERROR 


XKEY ( - addr ) 


CU3 


A system variable containing the compilation 
address of the code used by KEY. 


XNUMBER (-addr ) 


CU3 
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A system variable containing the compilation 
address of code called by the interpreter to attempt 
to decode a word not found in the dictionary. Set 
initially to attempt to decode the word as a number 
in the present base; if the number contains one or 
more decimal points the number will be taken to be a 
double number and DPL will be set to the position of 
the last such decimal point. If the word cannot be 
decoded as a number, the default code executes 
O ERROR- 


XOFF-CHAR ( - addr ) 

A variable containing ~1 or else the ASCII code 
of the variable used to temporarily pause execution. 
Typically set to the ASCII character XOFF, viz. 
control/S. See ?PAUSE. 


XOK < - addr ) lUl 

A system variable containing the compilation 
address of the code called to indicate normal return 
of control to terminal. 

XOR ( nl n2 - n3 ) C1743 

Leave the bitwise exclusive-or of two numbers. 


XPAGE <-addr ) CU3 

A system variable containing the compilation 
address of the code called by PAGE, usually to blank 
a screen or cause a paper throw. 


XPROMPT < - addr ) CU3 

A system variable containing the compilation 
address of the code always called just before control 
is returned to terminal. 
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XRUBOUT ( - addr ) 


CU1 



A system variable containing the compilation 
address of the code used in EXPECT to remove last 
character typed. 


XSIBhM^N < «ddr ) CUl 

A system variable containing the compilation 
address of the code called by ABORT just before 
control is returned to terminal. 




( - ) 


Cl,12S3 


End the compilation mode. The text from the 
input stream is subsequently executed. See 3. 
"left-braekef* 


C,3VARIABLE < nl n2 ++■»■ ) 

A defining word used in the form* 
nl n2 t,3VARIABLE <name> 

to create a dictionary entry for a two dimensional 
array of 16 bit integers, with rows numbered O to nl 
and columns O to n2. On later execution, 

n3 n4 <name> returns the address of the element in 
row n3 and column n4. 



CC0MPILE3 ( ++-»• ) LI,C, 1793 

Used in a colon definition in the forms 
CC0MPILE3 <name> 

Force compilation of the following word. This allows 
compilation of an IHMEDIATE word that would otherwise 
be executed, "bracket-compi1e" 


C3VARIABLE 


( n 1 ) 




! 

I 
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A defining word used in the -formx 
nl C3VARIABLE <name> 

to create a dictionary entry -for an array of 16 bit 
integers numbered O to nl. On later execution, 
n2 <na£ne> returns the address of element n2. 


3 <-) C1263 

Set the compilation mode. The text from the 
input stream is subsequently compiled. See C and 
LITERAL, “right-bracket" 



'^EMIT ( byte-) 

Strip the high bit of byte to convert it to a 
char, then if the result is a printing character, 
execute EMIT after having first executed CR if the 
value of OUT was not less than C/L. If the result is 
not a printing character, take a new line if the 
value of OUT is not at least 1 less than C/L. Then 
send to the output device, where X is replaced by 
the ASCII character formed by adding the value of 
char to the ASCII code for S). In the special case of 
ASCII 127, send 


''TYPE ( » -) 

Send the string s to the output device, using 
''EMIT for each character instead of EMIT. (This will 
wrap long lines and will print control characters 
visibly.) 


ch-in-«tr7 < char s - n ) 

If char is contained in s, return its position in 
s. Otherwise return zero. Note that for most 
purposes (e.g. testing with IF) n can be regarded as 
a true/false flag. 


I 



closa—files 


) 


7 n 
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Close all files that presently own virtual memory 
segments. 


copy (-) 

Copy the input spool to the output spool. 


count < Addr - addr n ) 

Return the number of characters in the string 
starting at addr and terminated by a null (zero 
byte). Used by EXPECT*. 


defdrv ( - n ) 

Return the presently selected (’default’) disc 
drive. Drive Ai is 1, Bs is 2 etc. 


eol? (-"flag ) 

Returns TRUE if the present input is exhausted. 


•xt ( - addr ) 

A variable containing the extent which will be 
opened by OPEN when it opens a file. For CP/M1.4 
systems only. Not normally for user alteration. 


faanign ( n file - ) 

Allocate the n’th virtual memory segment to the 
file. 


fdelete ( addr - flag ) 

Attempt to delete the operating system file 
corresponding to the file control structure at addr, 
returning TRUE if successful. 
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fnania! < * addr —■“ ) 

Let the name of the file control structure at 
addr be the string s, if the syntax of s is correct; 
otherwise execute ERROR. 


frelease < n - > 

Make virtual memory segment n belong to no file, 
flushing buffers and closing any file presently 
owning the segment if necessary. 


getc <-c ) 

Read the next character from the input spool. 
Return control/Z if the input is ended. The input 
spool is set up using the redirection words *== and << 
as described under the appropriate entries. 



in-«ddr ( --addr ) 

Return the address of the next byte looked at by 
the interpreter. 


in~rango? < nl n2 n3 - flag ) 

Return true if n2<=nl<=n3. 


maxdrv < - n ) 

Return the number of drives xForth thinks the 
system has. Set by CONFIG. 



n-TAB < n-) 

Print enough spaces to make the value of OUT a 
multiple of n, if this is possible without OUT 


I 20 
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equalling or exceeding C/L. Otherwise execute CR. 



put* < s-) 

Write a string to the output spool. See putc. 


putc ( c-) 

Write a character to the output spool. If there 
are any characters on the spool when control returns 
to the terminal, the spool is typed and left empty. 


seg-'Bize <-n > 

A constant returning the size of a virtual memory 
segment. (Set to lOOO on delivery.) 


Bkip-”Ch«r 





Pass over one character from the input without 
interpreting it, i.e. increment the input pointer 
unless the input is exhausted. 


•kip-until < char - ) 


Advance the input 
char has been reached 


pointer by zero or more until 
or the input is exhausted. 


•kip—while < char - ) 

Advance the input pointer by zero or more as long 
as char is found, stopping if the input is exhausted. 


wrap ( char - « ) 


Advance the input pointer by zero or more 
char is found or the input is exhausted. Return 
address and length of the string passed over in 


unti i 
the 
this 


I zo 
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way. Leave the input pointer beyond char. 

Used in conjunction with skip-while, this 
achieves the same effect as WORD but with a nor 0 ial 
rather than a packed string returned. One has the 
additional flexibility that empty strings may be 
dealt with. 



€ (flag —) 

If flag is true, continue execution^ if flag is 
false, advance the input stream pointer until a 
matching word I or > is found, then continue 
interpretation as usual. Used in the forms 

condition f do-if-true ... I do-if-false ... 

> 

where the? i and the do—if-false part are optional. 
This gives a limited form of IF ... ELSE EMDIF 

usable at execution time. f • > may be nested but 
little error checking is done- Note that all of f *. 
and > must be in the same input stream, i.e. in the 
same disc block or on the same? terminal input line. 
ERROR is executed if f with a false flag fails to 
find a matching \ or > before the input stream is 
ended• 


I < flag ™ ) 

Used in conjunction with C and >, giving an 
execution time version of ELSEI. See entry for <. 

If executed rather than skipped to, I causes the 
input pointer to be advanced until a matching > is 
found- If the end of the input stream is reached, 
ERROR is executed. 



> C — ) 

Used in conjunction with f and (optionally) S to 
give an execution time version of ENDIF. See entry 
for {- 

If executed rather than skipped to, > has no 
action. 
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Hords in xForth in addition to the FORTH-?? uords. 


STACK MANIPULATION 

?OROF t d — 1 Discard double itei on top of stack. 

2DiJP ( d — d d I Duplicate double itee on top of stack. 

2QVER ( dl d2 — dl d2 dll 

Copy second top stack double iten. 

2SHAP 1 dl d2 — d2 dl ) Exchanoc top tuo stack double itees. 

SP! ( any — 1 Discard all itees on stack, ’stack pointer store* 


COMPARISON 
<> 1 ni n2 — flag 


True if nl not equal to n2. *not-equar 


ARITHMETIC AND LOGICAL 

2t ( n — 2ln I Double the stack top. •teo-tiees* 

DABS ( d — Id! 1 Absolute value of a double nueber. 

Nt ( nl n2 — d I Double nueber signed product of signed single nuebers. 

S->D ( n — d ) Extend signed single nueber to signed double nueber. 


MEMORY 

H' 

S-! 

2 ' 

23 

<CflOVE> 


BLANKS 

ERASE 


( addr — 1 

( addr — 1 

( d addr — I 

I addr — d I 

( addrl addr2 u 


( addr n — ) 
( addr n —- I 


Add 1 to nueber at address, ’one-plus-store* 
Subtract 1 froe nueber at address, ’one-einus-store' 
Store double nueber d in 4 bytes starting at addr. 
Fetch double nueber froe 4 bytes starting at addr. 

Hove u bytes froe addrl to addr2, if u is nonzero, 
are handled correctly. 

Fill eeeory with o blanks starting at addr. 

Fill esoory eith n nulls starting at addr. 


Overlapping eoves 


CONTROL STRUCTURES 


CASE ... OF ... FJDOF ., 


EMDIF I — 1 

TERMINAL INPUT- 
>LIKE ( — addr ) 


ENDOF ... DEFWJLT ... ENDCASE ( n — 1 

Execute the first part beteeen the OF ... ENDOF for which the stack 
top on entry to CASE eatches the stack top on entry to OF . If no 
eatch. perfori the DEFAULT part if there is one. If no natch and no 
DEFAULT part, reoove the stack top. In all cases continue beyond 
ENDCASE. 

A synooyn for THEN 


7PAUSE 


7TERN1NAL 


CURSOR 


ENSURE-illE 


LAST-KEY 

OUT 


1 — 1 


I — flag 1 

( — ) 

( — 32 1 
( — 0 1 

( nl n2 — ) 


( n — 1 
( c — I 

1 c — I 

( n — I 

( ™ n ) 

( — char 1 
S — addr 1 

( — 1 


OUTPUT 

Return the address of a variable that is increeented by CR. Nay be 
used for 'paging’ a VDU. 

If IOFF-CHAR contains -1, do nothing. Otherwise execute 7TERNINAL 
and return at once if no key has been struck. If the key whose ASCII 
code is in IOFF-CHAR has been struck then wait until any key except 
control/C is struck before returning. If control/C is struck, either 
before or during the paused state, execute i ERROR. Notei CR calls 
7PAUSE so all words that produce output say he paused or interrupted. 
Return TRUE if any key has been struck, leaving the actual key to be 
read if desired fros LAST-KEY 

Send ASCII code 7 to the tersinal. This nornally sounds a 
noise-aaker. 

Constant returning ASCII code of a blank. 

Constant returning nuaber of characters in a line of output. (Set to 
80 on delivery.) 

Execute the code pointed to by XCURSQR. The code should aove the 
terainal’s cursor to row nl and coluan n2, relative to 0 0 as the top 
left corner. 

Perfora CR n tiees if n>0. 

Send c to the printer only, without increaenting OUT or checking what 
output is selected. 

Send c to the terainal only, without increaenting OUT or checking 
what output is selected. 

If there are less than n character positions reaaining on the present 
output line, execute CR . 

Constant returning nuaber of lines in a VDU screen. (Set to 24 on 
delivery.) 

Return the ASCII code of the last key read by KEY or ?T£RniNAL. 
Variable holding present position of output pointer. Increaented by 
EHIT, reset to 6 oy CR and adjusted by all other xForth output woros. 
Execute the definition pointed to by IPAGE. Usually causes a paper 


tnii, reset to u oy lk and adjusted c 
Execute the definition pointed to by 
throw or blanks a screen. 


jF i . e 0 




PfilHTER-OH? 

1 — addr ) 

TAB 

( n — ) 

XOff-CHAR 

f — addr ) 

trap 

1 char — s ) 

1 

'^EhlT 

( byte — } 

'TYPE 

(5—1 

NUMERIC 

.BASE 

.R 

CONVERSION 
{ — ) 

1 nl n2 — ) 

BihARY 

D. 

D.R 

( — > 

( d ™ » 

( d n — 1 

HEX 

( — ) 

MASS STORAGE INPUT 
ffiles ( — n 1 

•s-fCB 

( addrl — addr2 ) 


( addr — s 1 

•th-FILE 

( n — addr 1 

-> 

« 

( — ) 

1 ♦♦♦ 1 


1 — 1 

» 

( *** 1 

COPIES 

( ni n2 n3 — 1 

COPY 

CPh-CALL 

( nl n2 — 1 
( nl byte — n2 1 

CPh-CALLb 

( 0 bytel — byte2 

DIR 

( n — ) 

INDEX 

{ nl n2 — 1 

mmi-m 

( ) 

LIST-FILE 

{ } 

LOAD-FILE 

{ ) 

P! 

P3 

( bytel byte2 — ) 

( bytel — byte2 1 

PREV 

( — addr ) 

SEE 

( n — 1 

SEE-FILE 

( ♦♦+ 1 


A virisbU* thit it 55 1 to i ciassfs outpus, ... ae copiwj to ths 
printer. Toggled by control/P during EXPECT or aay be set and reset 
under progras control. 

Type as aany spaces as needed to bring the output pointer to position 
n, it possible. Otherwise do nothing. 

A vari^le containing the character used in ’PAUSE to pause 
execution. H it contains -I, ?PAUSE oill never atteept to read the 
keyboard. Set to control/S on delivery. 

For the input presently being interpreted, advance the pointer until 
char is Found or the input is exhausted. Return the address end 
length of the string passed over in this uay. Leave the input 
p^ointer beyond char. 

Execute Efin For the ASCII value Fomed fros the louer 7 bits oF 
byte, taking a new line iF the value oF OUT exceeds C/L. !F the value 
is 127 then type *? IF the value is less than 32 then EfllT * 

Followed by Abtll value 644^value. (So 3 *£HIT gives ''C ! 

As TYPE but use '‘EMIT to type each character. 


Type the present base For nueeric input/output, in decieal. 

Type a signed nuober in the current base, right aligned in a Field oF 
width n2. 

Set the bass For outeric input/output to 2. 

Type a signed double nuaber in the curreot base, Followed by a blank. 
Type a signed double nuaber in the current base, right aligned in a 
Field oF width n. 

Set the base For nuaeric input/output to 16. 

/OUTPUT AND VIRTUAL MEMORY 
A constant returning 8, the nuaber oF virtual aeaory segaents 
noraally accessible to the user. 

Siven tne address addrl oF a File control structure, return the 
address addrZ oF a part oF aeaory used to coaaunicaie File control 
ioForeatton with the operating sysiea. 

Siven the address of a File control structure, return the address and 
length of a string containg the ASCII naae oF the corresponding CP/H 
file. 

Return the address of the File control structure owning the n'th 
virtual aeaory segaent, if this segaent has been allocated to a File. 
Otherwise return 0. 

Continue interpretation with the next block, ‘next block* 

Read the next word in the input streaa as a CP/H File naae, and sake 
that File the spooled input For reading with getc. "redirect-in* 
Hake the previous spooled output For putc the new spooled input For 
oetc. *pipe* 

Read the next word in the input streaa as a CP/n File naae, and copy 
to that File the spooled output written previously by putc. 
*redircct”Out* 

Copy block nl to n2, nUi to n2ai etc until n3 blocks have been 
copied. Overlapping shifts are done correctly. 

Copy block nl to n2. 

hake a call to the CP/h systea For Function byte with nl in the OE 
register. The contents of the HI register on return are left as n2. 

Execute CPh-CALL and aask off all but the lew order byte of the 
result. 

Display the directory of the disc in CP/h drive n, where n=l gives 
drive A and so on. 

Type the first 64 characters each of blocks nl to n2. hay be stopped 
by hitting any key. 

Read the next word Froa the input streaa as a CP/h File and aake it 
the CP/h naee of a teaporary File owning the segaent of virtual 
■eaory beyond the last user-accessible segaent. 

Read the next word froa the input streaa as a CP/h file naae and list 
the File in LIST Fora if the File extension is .ELK Otherwise 
assuae the File is an ASCII text file and list it as such. 

Read the next word Froa the input streaa as a CP/h File nase and LOAD 
the First block of the File if the file extension is .BLK 
Send byte! to the port address given by byte2. 

Return the byte obtained by inputting Froa the port address given by 
bytel. 

Systea variable containing nuaber of block aost recently referenced 
via BLOCK. High bit of block nuaber is set if block is updated. 
Invoke the screen editor with the cursor pointing to the first 
character of block n. 

Read the next word Froa the input streaa as a CP/H File naae and 
invoke the screen editor with the cursor pointing to the first 
character of the File, if the File extension is .BLK 
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TRIAD 

( n — ) 

WHERE 

( nl n2 -- ) 

copy 

( — ) 

fassign 

( n file — 

frelease 

( n — ) 

getc 

( — c ) 

putt 

( s — ) 

putc 

( c — ) 

seg-size 

( — n ) 

DEFINING 

WORDS 

FILE XXX 

( *** ) 

STRING XXX 

( n ♦♦♦ ) 

XXXI ( — s 

[,]VARIABLE XXX 

( nl n2 I 

XXXI ( nl n2 

□VARIABLE XXX 

( n ♦♦+ ) 

XXXI ( n — 

VOCABULARIES 

(EDITOR) 

( — ) 

ASSEMBLER 

( — ) 

DEBUG 

( — ) 

EMPTY 

( — ) 

VLiST 

( — y 

COMPILER 

9 

(♦♦♦si 

IFIND 

( s — addr 1 

INTERPRET 

( — ) 

c, 

( byte — ) 

MYSELF 

( — ) 

WIDTH 

( — addr 1 

eol? 

( — flag ) 

in-addr 

1 — addr 1 

skip-char 

( — 1 

skip-until 

( char — ) 

skip-while 

( char — ) 


itrap 


( char — s ) 


viik' ituufcis. ur a kviiVifui suuukjre oaniitfi rtftuai iieaory 
segaent 0. (Blocks 1 to 999 in the standard systea). 

Type 3 blocks, including block n, in a (ora suitable for hard copy. 
Invoke the screen editor with the cursor pointing after character nl 
of block o2. If used after ERROR, Kill leave the cursor just after 
the aord ahere the error was detected. 

Copy the input spool to the output spool. 

Allocate the n’th virtual aeaory segsent to the file. 

Release the n’th virtual aeoory segaent so that it belongs to no 
file. 

Read the neat character froa the input spool. Return control/! if 
the input is ended. 

As putc but arites a string. 

irite a character to the output spool. 

A constant returning the size of a virtual aeaory segaent. (Set to 
1000 on delivery.) 

See entry under HASS STORAGE. 

Create a strino variable to hold a text string cf length up to n 
characters. It n exceeds 256, the aaxiaua length ailf be 256. 

Returns address of first character and current length of string when 
executed. 

Create a too dieensional array of 16 bit integers, «ith roas nuabered 
0 to nl and coluans 0 to n2. 
addr I 

Returns address of eleaent in roa nl and colusn n2 when executed. 
Create an array of 16 bit integers nuabered 0 to n. 
r 1 Returns address of eleaent n ahen executed. 

The vocabulary of internal screen editor words. 

The vocabulary of asseabler words. 

The vocabulary used for debugging and tracing. 

Reaove all unprotected definitions without altering the stacks. See 

rKUIkLI a 

List all the words in the present context vocabulary, and all 
vocabularies contained in it. Kay be stopped by hitting any key. 

Return address and length of string terainated by next * 

If used in a definition, return address and count when executed. 

Like FIND, but uses s instead of reading a word froa the current 
input. 

Execute (or coapile, if STATE is nonzero) the text froa the present 
input. The input is froa the keyboard if the value of BLK is nonzero 
and froa the virtual aeaory block nuabered by BLK otherwise. 

Coapile a byte into the dictionary. 

SSJBf).® * to the latest definition (usually the definition 

niSELF 15 contained in). Allows recursion. 

Systea variable containing aaxiaua length stored In dictionary for a 
naae. The interpreter stores the nuaber of characters in the naae 
and its natural characters up to the value in WIDTH. The default is 

w 1 « 

Returns TRUE if present input is exhausted, ’end-of-line'?* 

Return address of next byte looked at by interpreter. 

Pass over one character without interpreting it. 

Advance the input pointer until char has been reached or the input 
IS exhausted. 

Advance the input pointer as long as char is found, stopping if the 
input is exhausted. 

For the input presently being interpreted, advance the pointer until 
char is found or the input is exhausted. Return the address and 
length of the string passed over in this way. Leave the input 
pointer beyond char. 


TEXT STRI 

• ( 


*! ( 

♦♦ ( 

*< ( 

«->l ( 


I* ( 

ASCII ( 


NGS AND CHARACTERS 

*** s 1 Return address and length of string tereinated by next ’ 

IT used in definition, return address and count when executed, 
si s2 — I Assign the string literal si to the string variable s2, truncating si 
at the right if necessary, 
si 52 —- 63 ) Concatenate strings, 

si s2 — flag ) Return TRUE if si is lexically prior to s2. 

s --- d flag ) Return TRUE if s contained only digits and, optionally, a leading 

emus sign. If TRUE is returned then d is the value of the nuaber 

represented by s in the current base, 
si 52 — flag ) Return TRUE if the strings are identical. 

char ) Read the next word froa the input and leave the ASCII code of its 
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EIPECTt 


< — 32 I 
( ♦♦♦ ch*r J 

( addr n — s ) 


(tkip-until) ( addri char 


(skip** white! 

1 addrl char - 

EXECUTION VARIAl 

REPLACED-BY 

( addr +♦♦ ) 

TCANCEL 

( — addr ) 

ICURSQR 

( — addr ) 

lEMlT 

( — addr i 

(ERROR 

( — jddr ) 

IKEY 

< — addr ) 

(NUMBER 

( — addr ) 

(OK 

1 ™ addr ) 

(PROMPT 

( — addr ) 

(RU80UT 

1 — addr ) 

(SISHON 

( — addr ) 

C0N8TANTS 

BL 

( — 32 ) 

C/L 

( — n ) 

FALSE 

{ — 0 ) 

L/S 

( ™ n ) 

TRUE 

( — 1 ) 

ERROR 

HANDLIN6 

7C0MP 

( ™ ) 

7DEPTH 

( n — ) 

TERROR 

( flag n — 

7£(£C 

( ~ ) 

7L0ADIK8 

( ™ ) 

7PA1RS 

( nl n2 — ) 

7STACK 

{ — ) 

ERROR 

( n — ) 

MESSAGE 

( n — ) 

STD-ERSOR 

( n — ) 

MARN1N6 

( — addr ) 

in-rangf? 

( nl n2 n3 — 

ASSEHBLER 

CODE XXX 

( ♦+♦ ) 

END-CODE 

( — ) 

LABE. XXX 

( ♦♦♦ ) 


first character. 

Return the ABCII codt of a blank. 

Read the neat nord froa the input and leave the lou order S hits of 
the ASCII code of its first character. 

) Read up to n characters froa the keyboard as for EkPECT) storing thea 
at addr. Return a string denotation, consisting of addr and the 
actual nuaber of characters typed. 

- addr2 I 

Increase addrl by 0 or aore until the byte address pointed to 
contains char or 0. 

- addr2 ) 

Increase addrt by 0 or sore until the byte address pointed to does 
not contain char or does contain 0. 


Find the execution code of the next uord in the input streaa, and 
store it in addr. 

Points to execution code used in EIPECT to cancel all input. 

PoinU to execution code used by CURSOR. 

Points to execution code used by EMIT. 

Points to execution code used by ERROR. 

Points to execution code used by KEY. _ 

Points to execuUon code used by HUMBER. This is called by INTERPRET 
to decode a uord that cannot be found in the dictionary. Uy default, 
it atteapts to decode the uord as a nuaber (or as a double nusbtr if 
it contains I or aore deciaal points) in the present BASE, and calls 
0 ERROR if it fails. , . , 

Points to execution code called to indicate noraal return of control 
to terainal. 

Points to execution coda always called just before control is 
returned to terainal. 

Points to execution code used in EIPECT to reaove last character 


Points to code called by ABORT just before control is returned to 
terainal. 


Return the ASCII code of a blank. 

Return the nuaber of characters per line in noraal input/output. Si 
by C0MFI6. Typically BO. 

Return the value of a FALSE flag. 

Return the nuaber of lines per page (i.e. per VDU screen) in noraal 
input/output. Set by CONFIG. Typically 24. 

Return the value of a TRUE flag. 


Error if not coapiling. 

Error if stack bat less than n entries below n itself. 

If flag is TRUE, call n ERROR. If flag is false, reaove it and n 
and continue noraally. 

Error if not executing. 

Error if not loading froa virtual aetory. 

Error if nl is not equal to n2. Used in checking syntax of 
conditionals. 

Error if stack is out of bounds. r a. a. 

Eaecute the definition i»hose code field address is in XERROR, Set to 
8TD-ERRQR on delivery. 

Type error wssage n but continue noraally. 

Issue error tessage n, clear stacks, and obey QUIT. 

A systee variable used for error handling. If its lowest order bit 
is set to 1, error eessages are read froa blocks 4 onwards of 
If this bit is set to 0, nuaeric error aessages are given. If the 
high order bit is set to I (i.e. the value is negative), warning 
aessages are suppressed whatever the value of the low order bit 
although true errors are caught as usual, 
flag ) 

True if n2<*nl<»n3. 

Begin definition of word in asseabier code. 

End CODE or jCODE definition. ^ , l 

Insert a label in the dictionary and set the CONTEXT vocabulary to 
ASSEKBLER. 
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lYE 

COLfi 


CWiG 

PfiaiECT 

SVSADAPT 

8YSSEM 

iARfl 


( — 1 Gill SAV£-SSjfFERS and then return control to the operatinq systee. 

( — > Reset the systea to the state it had uhen PROTECT aas last called, ar 

to the initial start-up state. This includes reaoyinq all nee 
detinitions, resetting the filing systea aithout saving buffers or 
closing files, and resetting all systea and etecutian variables. 
Finally call ABORT. 

( — ) Equivalent to 2 LOAD. Set up on delivery to ask the user for the values of 

BEL-KEY etc, then alloN the user to change the editor key bindings if 
desired, and finally to execute 6YSADAPT with a 'reasonable' nueber 
of buffers. 

$ — 1 Set the initialisation sequence so that the present state will be 

restored by COLD. 

in — 1 Call PROTECT then set the initialisation sequence so that n buffers 

Mill be used for virtual neiory, and all possible eesory ttill be 
used. Then call COLD. 

( — ) Senerate the standard syste# fros the kernel systee. 

( — I Call ERPTY-SUffERS and then ABORT. 






I 


! 

I 
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STACK ^MANIPULATION 

CHJP ( n n n ) 

DROP ( n - ) 

SWAP ( n1 n2 n2 n1 ) 

OVER (rR n2 -- nl n2 n1 ) 

^OT (n1 n2 n3 ^ 02 n3 n1 

PiCK { n1 - 02 ) 


Slack inputt and outputa ara ahov>^n; lop o( alttck cm r«yht operand a? ijoitom. 




CHJP 

DROP 

SWAP 

OVER 

ROT 

PiCK 

ROLL 

?OUP 

>R 

R> 

DEPTH 


(n -» ) 

{ n - n (n)) 

(n - ) 

( -n) 

{ --n) 
i -n) 


Duplicate top of stack. 

Discard top of stack. 

? n1 ) Exchange top two stack items. 
n2 n1 ) Make copy of second item on top. 
n2 n3 nl) Rotate third item to top. “rote** 

Copy nl-th item to top. (Thus 1 PICK = DUP , 2 PICK « OVER ) 

Rotate n-th item to top. (Thus 2 ROU »« SWAP . 3 ROLL = ROT ) 
Duplicate only if non-zero. “Query-dup" 

Move lop item to “return stack” for temporary storage (use caution), “to-r” 
Retrieve item from return stack. *T-from" 

Copy top of return stack onto stack, “r-fetch" 

Count fUimb^^r of Items on slack. 


COMPARISON 


( nl n2 flag) True if nl less than n2. “less-thon” 

(nl r^ flag ) True if lop two rximbers are equal, “equals" 

( nl ri2 - flag ) True if nl greater than n2, "greater-than” 

( n — flag) True li top r^umber negative. “leroHess" 

{ n ^ flag ) Ta^e it top number zero. (Equivalent to NOT ) "zero-equals" 

( n - flag ) True if top number greater than zero, ‘‘zero-greattr” 

( dt (12 flag ) True if dl less than d2 "d-less-than" 

( unt ua2 — flag ) Compare top two items as unsigned integers, “u-less-than" 
(flag -(flag ) Reverse truth value (Equivalent to 0— ) 


ARITHMETIC AND LOGICAL 

-F 

( nl f\2 — sum ) 

0-F 

( dl d2 - sum) 

— 

( nl n2 - diff) 

t-F 

( n n-Ft ) 


(n - n*~ ) 

2-F 

( n n-F2 ) 

2- 

( n n~2 ) 

• 

( nl n2 - prod ) 

/ • 

( nl rC? - quo!) 

MOO 

( nl n2 rem ) 

/MOO 

( nl n2 - rem quo!) 

•/MOD 

(n 1 02 03 -* rem quot | 

V 

{ nl fT2 rC - quot) 

U* 

( uni ua2 ud ) 

U/MOO 

( ud un — urem uquot! 

MAX 

( n 1 n2 - max ) 

MIN 

( nl ri2 - mm ) 

ABS 

( n Ini) 

NEGATE 

( n - -n ) 

DNEGATE 

(d - -d) 

AND 

( nl n2 - and ) 

OR 

( nl f\2 - Of) 

XOR 

( nl n2 - xof) 


Add. “plus” 

Add double-precision numbers ”d-plus” 

Subtract {nl~-n2) “minus” 

Add 1 to top number, “one-plus” 

Subtract 1 from top number “one*minus" 

Add 2 to top number, “two-plus" 

Subtract 2 from top ruin^ber. “two-minus” 

Multiply “times’* 

Divide (nt/n2). (Quotient rounded toward zero) "divide” 

Modulo (/.e., remamder from division ntjn2). Remainder has same sign as nl. "mod" 

Divide, giving remainder and quotient, "divide-mod" 

Multiply, then divide (nl*n2/n3). with double-precision Intermediate, "limes-divide-mod" 

Like ‘/MOO . but give quotient only, rounded toward zero, "times-divide** 

Multiply unsigned numbers, leaving unsigned double-precision result. “u-timea“ 

Divide double number by single, giving remainder and quotient, ail unsigned, “u-divide-mod" 
Leave greater of two ruimbers. **max” 

Leave lesser of two numbers "min” 

Absolute value, “absolute" 

Leave two's complement. 

Leave two's complement of double-precision number, “d-negate” 

Bitwise logical AND. 

Bitwise logical OR. 

Bitwise logical exclusive-OR "x-or” 


MEMORY 


MOVE 

CMOVE 

fill 


( uddr — n ) 

( n addr - ) 

( addr -*» byte ) 

( n uddr - ) 

( addr — ) 

( n addr - ) 

( addrl addr2 n - ) 
( addr I addr2 n - ) 
{ uddr n byte - ) 


CONTROL STRUCTURES 


00 ., LOOP 
I 

J 

LEA^VE 

DO ... -FLOOP 

IF, (true). .THEN 
fF ... (true).., ELSE 

(false)... Then 

BEGIN .. . UNTIL 
BEGIN WHILE 
REPEAT 

EXIT 

EXECUTE 


do; (erid-FI start 

( - ifxlex) 

( irKjex) 

( - ) 

ck); (limit Stan 
■Floop; ( n ) 
if; (flag - ) 

If; (flag - ) 

until: (flag -• ) 
while: (flag - ) 


(addr — ) 


Ruplace address by number at address, "fetch” 

Store n at addr. "store” 

Fetch least significant byte only, “c-lotch" 

Store least signticant byte only, “c-store" 

Display number at address, "question-mark” 

Add n to number at addr. “plus-store" 

Move n Plumbers starting at addrl to memorv starting at addr2. if n>0. 

Move n bytes starting at addrl to memory starting at addr2. if n>0. “c-move" 
Fill n bytes in memory with byte beginning at addr. if n>0. 


Set up loop, given index range. 

Place current loop index on data stack. 

Returrb index of next outer loop in same definition. 

Terminate loop at next LOOP or *f LOOP , by setting limit equal to index. 

Like DO . LOOP. but adds stack value (instead of always 1) to index. Loop termir^ates when 
index IS greater than or equal to limit (n>0). or when index is less than limit (n<0). “plus-loop” 
If top of stack true, execute. 

Same, but if false, execute ELSE clause. 

Loop back to BEGIN until true at UNTIL . 

Loop while true at WHILE; REPEAT loops unconditionally to BEGIN. When false, CJontlnu® after 
REPEAT. 

Terminate execution of colon definition. (May not be used withiri DO ... LOOP ) 

Execute dictionary entry at compilation address on stack {e.g., address returiied by FIND ). 


t <3 0 


Ofmmnd key* 

n, nt. ... id-Ut tigned numbeia 


d, dl,... 32*bi! signed ruimbers 
u unsigned 


addr, addrl, ... addresses 
byte a-bit byte 


char 7*blt ascii character value 
flea tjool«.sn fleo 







CH 

EMIT 

SPACE 

SPACES 

TYPE 

COUNT 

-TRAIUNQ 

KEY 

EXPECT 

QUEf^Y 

WORD 

NUMERIC 

BASE 

DEClUAi 

U. 

CONVERT 


^ ) Do a carrtaga return and line feud. *‘cY‘ 

( chef - ) Type aacii value from alack 

^ ) Type one space. 

^ ) Type n spaces, If n>0. 

( addf n — ) Type stfing of n characters beginning at addr. if n>0. 

I a^ - eddf^l n ) Change address of suing (prefixed by length byte at addr) to TYPE form. 

addr n1 - addr n2 ) Reduce character count of string at addr to omit trailing blanks, “dash-trailina'* 
t “• cnar) Read key and leave ascii value on stack. 

( n - ) Read n characters (w until carriage return) from terminal to address, vinth nuiifs) at end 

J > 90 characters from terminal to input buffer 

( - addr) Reed r^ext word Uom Input stream using char as dclimitur, or until null. Leave addr of length byte. 

CONVERSION 

( - addr) System variable containing radix for numeric conversion. 

( ) Set decimal number base. 

j " ■“ ) Pf'nf number with one trailino blank and slQn If nooative “dor 

!1? . .. . u.naianed number with one trailing blank “u-dot" 

dl adon - d2 addr2 )^nvertstnnoataddrt+1 to double number Add to d1 leaving sum d2arxl addr? othratnon^ioit 
t ) Start numeric output string conversion, “less'sharp” non-a g i. 

{ udl - od2 ) Convert next digit of unsigned double number and add character to oetmit xirhin 

ud ^ 0 0 ) Convert all aignilicant digits ol unsigned double number loTtpul 

(Char - ) Add ascii char to output string. ^ ^ ® 

("^ ) Add minus sign to output string if n<0. 

{ d - addr n ) Drop d and termirmte numeric output string, leaving addr and cotmt for TYPE. "sharp-greater 


MASS STORAGE INPUT/OUTPUT 


UST 

LOAD 

SCR 

BLOCK 

UPDATE 

gMJEFER 

SAVE-BUFFERS 

EMPTY-BUFFERS 


(n - ) 

(n - ) 

( -- addr) 

( n - addr) 

i ) 

{n addr) 

( -- ) 

( - ) 


DEFINING WORDS 

XXX < ^ ) 

VARlABLExxx ( - ) 

XXX ( addr) 
CONSTANT XXX ( n - ) 

xxx( n) 

VOCABULARY XXX ( - ) 

CREATE ... OOES> does: ( addr) 

VOCABULARIES 

CONTEXT (-addr) 

CURRENT ( - addr) 

FORTH ( - ) 

DEFINITIONS ( - ) 

' ( - addr) 

FIND I addr) 

FORGET XXX ( ) 


Usl screen n and set SCR to contain n. 

Interpret screen n. then resume irUerpreration of the current input stream. 

System variable containing screen number most recently listed. 

Leave memory address of block, reading from mass storage if necessary. 

Mark last block referenced as modified. 

Leave addr of a tree buffer. ass>gne<3 to block n. vmte previous contents to mass storaoe if 
Write all UPOATEd blocks to mass storage 

Mark all block burters as empty, without writing UPDATEd blocks to mass storage. 

Begin colon definition of xxx "colon” 

End colon definition. "semFcolon” 

Create a two-byte variable named xxx ; returns address when executed. 

Oeate a constant named xxx with value n; returns value when executed. 

Create a vocabulary named xxx ; becomes CONTEXT vocabulary when executed 

Used to create a new defining word, with execution-time routine in high-level FORTH, “does” 

System variable pointing to vocabulary where word names are searched for. 

System variable pointing to vocabulary where new definitions are put 

Find address of xxx in dictionary; jf used in definition, compile address, “tick" 

Uttve compilation address of r>ext word in input stream K not f ourxf in CONTEXT or FORTH, leave 0. 
Forget all definitions beck to and mciuding xxx , which must be in CURRENT or FORTH. 


COMPILER 


IMMEDIATE 

UTERAL 

STATE 


CC)MPIL£ ( . 

(COMPtLEl ( - 

MISCELLANEOUS 


) 

(n - ) 

( - ) 

( ) 
(n- ) 

( - addr) 

( - ) 

( ) 

( ) 

( ) 


HERE 

PAD 

>IN 

BLK 

ABORT 

ourr 

79-STANOARO 


( *“ ) 

( addr) 
( - addr) 
( — addr) 
( - addr) 
( - ) 
i - ) 

< ) 


Compile a number Into the dictionary, “comma" 

AcW two bytea to the parameter field of the most recenftydofined word. 

f^nt message (terminated by '). If used in definition, print when executed, “dot-quote” 

Mark last-defined word to be executed when encountered In a definition, rather than compiled 
n compiling, save n in dictionary, to be returned to stack when definition ta executed 
System variable whose value is non-zero when compilation Is cw^currlng 
Stop compiling input text and begin executing, "left-bracket" 

Stop executing input text and begin compiling, “right-bracker 
^pile the address of the next non-IMMEOIATE word into the dictionary 
Compile the foUowlng word, even if IMMEDIATE “bracket-compile" 

Begin coj^nt terminated by) on eame line or aaeen; space after (. “paren” •'closertjaren- 
Leave address ol nexi available dictionary location. t"-*' . crose-paron 

Leave address of a scratch area of at least 64 bytes. 

System venule containing character offset info input butler; used, •.a, by WORD “to-ln” 

number currently being Interpreted, or 0 If from terminal "b-kk" 
ni, stacks, set execution mode, return control to temtinal. 

UKe ABORT . except does not clear data stack or print any message 
Verify that system conforms to FORTFF79 Standard. 
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Please till in and sign this :.^greement and return it with your orciar. 
Although the licence only t:overs a single coflriputer, it (nay foe extended 
at a reduced price by agreement with us. It you sell your computer, 
we may transfer the licence to the new o^^ner for a nominal charge. 
Registering with us means you will tje abie to get updates and new 
manuals at specially reduceo prices. 


A. 1. fi. Researc'.* 

20 Montague Road, Camoridge C&4 IBX. 


Software Licence Agreement. 

A.I.M. Research agrees to grant and the customer signing below 
(hereinaiter *'the Customer**) agrees to accept on the following 
conditions a non-transfer abl e and non--excl usi ve licence to use 
the software detailed below ("the Saftwari*") on the computer 
system detailed below ("the System**). 

The Software may be used in any machine-readable form on the 
S/stem by the Custonier or by others under the Customer's personal 
su^^ier VI SI on. Any number of copies of the Software may be made 
tor use on the System under the conditions of this licence. 

Th^ Software may be modified or adapted for use on che System 
but neither in its original nor in its modified form may the 
Software be sold or otherwise transferred without the prior written 
consent of A.I.M. Research. In this context, transfer includes 
but IS not restricted to any means by which the source code, 
the executable code or the design of the software may be made 
available, directly or indirectly, for use by anyone who is 
not a licence holder. 

In the absence of a specific written agreement by A.I.M. Research 
that the Software is suitable for a given purpose, the liability 
of A.I.M. Research shall be restricted to the replacement of the 
Software or, at our option, the refund of its purchase price. 


Cuu t umer: 
Namt^: 


Piddr ess: 


Si gnature: 
Date; 


Syut em: 

Ha. iuf ac turer; 
Model : 

Operat 1 ng system: 


Ser 1 ai number s 
^>er 1 a i nuaiber : 


Sof twares xForth 




